CRM and sales
Send Contracts From HubSpot Deals
Send a SignatureAPI contract when a HubSpot deal reaches a stage, using a workflow custom code action, and receive the result with a webhook trigger.
A HubSpot workflow can send a contract when a deal reaches a stage. HubSpot’s Send a webhook action builds its own key and value body, and its documentation doesn’t list custom headers, so this page uses a Custom code action that calls the SignatureAPI REST API directly. No SignatureAPI app is needed.
Before you start
- A SignatureAPI test API key (it starts with
key_test_). - The document you send, at a URL on a supported host, or uploaded to SignatureAPI first. The examples use a sample PDF.
- A HubSpot account with Data Hub Professional or Enterprise. HubSpot requires it for custom code actions and for the Send a webhook action.
Send the envelope
Create a deal-based workflow
Create a workflow on deals that starts when the deal reaches your contract stage, then add a Custom code action and choose the Node.js language.
Store the key as a secret
In the action, click Add secret, enter SIGNATUREAPI_KEY as the Secret name and your key as the Secret value, then click Save. The code reads it with process.env. HubSpot limits all secret values together to 1,000 characters.
Pass the deal values
Under Property to include in code, click Select a property and add the deal id, the company name, and the properties that hold the signer’s name and email. Enter the Property name the code reads: dealId, company, name and email.
Add the code and an output
Paste the code below. Under Data outputs, click Add output, choose a string Data type and enter envelopeId as the Name, so a later action can use the new envelope id.
const axios = require('axios');
exports.main = async (event, callback) => {
const input = event.inputFields;
const response = await axios.post(
'https://api.signatureapi.com/v1/envelopes',
{
title: `Service Agreement - ${input.company}`,
message: 'Please review and sign the service agreement for your order.',
metadata: { source: 'hubspot', deal_id: input.dealId },
topics: ['no_code', 'hubspot'],
documents: [
{
key: 'service_agreement',
url: 'https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf',
format: 'pdf',
fixed_positions: [{ place_key: 'signer_signature', page: 1, top: 172, left: 210 }],
places: [{ key: 'signer_signature', type: 'signature', recipient_key: 'signer' }],
},
],
recipients: [{ type: 'signer', key: 'signer', name: input.name, email: input.email }],
},
{ headers: { 'X-API-Key': process.env.SIGNATUREAPI_KEY } },
);
callback({ outputFields: { envelopeId: response.data.id } });
};data.envelope_metadata.deal_id comes back in every webhook event for this envelope, and the hubspot topic lets an endpoint receive only these envelopes. axios is one of the libraries HubSpot lists for Node.js custom code, and the action must finish within 20 seconds.
Get the result back
HubSpot workflows can start from an incoming webhook. In HubSpot, open Automation > Workflows, choose When a webhook is received under Custom events & external events, and copy the URL it gives you. HubSpot accepts only application/json and enrolls a record only when a webhook field matches a unique property on an existing record. HubSpot’s article lists the editions that include it.
Store the envelope id on the deal
Create a deal property with Require unique values for property turned on. After the code action, add an Edit records action that sets it to the envelopeId output.
Register the URL in SignatureAPI
In the Dashboard, add a webhook endpoint in test mode with the HubSpot URL. Subscribe to deliverable.generated, which fires when the signed PDF is ready, and add the hubspot topic. The envelope.completed event comes earlier, while the PDF may still be generating, so use it only to update a status. Send a test envelope to yourself and sign it, so HubSpot receives a real event to read, then map data.envelope_id from the event to your unique property.
Read the envelope before you act
Anyone who knows the webhook URL can call it, so read the envelope with your key before you update the deal. Add a second Custom code action that sends this request with the same secret:
HTTP request step
Settings for the "Completed envelope" request.
| Setting | Value |
|---|---|
| Method | GET |
| URL | https:// |
| Header | X-API-Key: YOUR_API_KEY Store the key in your tool's secret or credential storage when it has one. |
Act on the response: deliverable.status is generated, metadata.deal_id names the deal, and deliverable.url downloads the signed PDF. That link expires after an hour, so download the file in the same run. If your account uses authenticated deliverable URLs, send your API key with the download.
SignatureAPI expects a 2XX answer and retries a failed delivery for up to 48 hours. The same event can arrive twice, so skip it when the deal already shows the contract as signed. See Webhooks.
Related
- Create an envelope: every field of the request body.
- Organize with topics and metadata.
- Make, Zapier and n8n use the same request.
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Service Agreement - Acme Corp",
"message": "Please review and sign the service agreement for your order.",
"metadata": {
"source": "hubspot",
"deal_id": "50055"
},
"topics": [
"no_code",
"hubspot"
],
"documents": [
{
"key": "service_agreement",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "signer_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "signer_signature",
"type": "signature",
"recipient_key": "signer"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "signer",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"title": "Service Agreement - Acme Corp",
"message": "Please review and sign the service agreement for your order.",
"metadata": {
"source": "hubspot",
"deal_id": "50055"
},
"topics": [
"no_code",
"hubspot"
],
"documents": [
{
"key": "service_agreement",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "signer_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "signer_signature",
"type": "signature",
"recipient_key": "signer"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "signer",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"title": "Service Agreement - Acme Corp",
"message": "Please review and sign the service agreement for your order.",
"metadata": {
"source": "hubspot",
"deal_id": "50055"
},
"topics": [
"no_code",
"hubspot"
],
"documents": [
{
"key": "service_agreement",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "signer_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "signer_signature",
"type": "signature",
"recipient_key": "signer"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "signer",
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
]
}
}{
"id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"title": "Service Agreement - Acme Corp",
"label": null,
"message": "Please review and sign the service agreement for your order.",
"status": "processing",
"attestation": "none",
"language": "en",
"mode": "test",
"routing": "sequential",
"timezone": "UTC",
"timestamp_format": "MM/DD/YYYY HH:mm:ss",
"snapshot_url": null,
"branding": {
"logo": null,
"accent_color": "#2463EB",
"email": {
"footer": null,
"logo_position": "left",
"from": "noreply@signatureapi.com"
}
},
"deliverable": {
"id": "del_6FF89lKNyTNamOJCJd1tLL",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"name": null,
"status": "pending",
"type": "standard",
"url": null,
"password": null,
"created_at": "2026-11-02T14:03:11.000Z",
"generated_at": null,
"timezone": "UTC",
"language": "en",
"timestamp_format": "MM/DD/YYYY HH:mm:ss",
"included_documents": [
"service_agreement"
]
},
"metadata": {
"source": "hubspot",
"deal_id": "50055"
},
"sender": {
"name": "Acme Corp Legal",
"email": "legal@acme.example",
"organization": "Acme Corp"
},
"captures": {},
"documents": [
{
"id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"key": "service_agreement",
"title": null,
"page_count": 1,
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"page": 1,
"top": 172,
"left": 210,
"place_key": "signer_signature"
}
],
"places": [
{
"key": "signer_signature",
"type": "signature",
"recipient_key": "signer",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_49r1R2jpPDz8hSpP75ZkPp",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "signer",
"key": "signer",
"email": "jane.doe@example.com",
"name": "Jane Doe",
"ceremony": {
"authentication": [
{
"type": "email_link",
"subject_override": null,
"message_override": null
}
],
"embeddable_in": [],
"redirect_url": null,
"redirect_delay": 3,
"url": null,
"url_variant": "standard"
},
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": [
"typed",
"drawn"
],
"status": "pending",
"status_updated_at": "2026-11-02T14:03:11.000Z",
"completed_at": null
}
],
"topics": [
"no_code",
"hubspot"
],
"created_at": "2026-11-02T14:03:11.000Z",
"completed_at": null
}{
"type": "https://signatureapi.com/docs/v1/errors/validation-error",
"title": "Validation Error",
"status": 422,
"errors": [
"recipients[0].email must be a valid email address."
]
}Errors every call can return are in Errors and Authentication.