---
title: "Send Contracts From HubSpot Deals"
description: "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."
canonical: "https://signatureapi.com/docs/integrations/hubspot"
source: "https://signatureapi.com/docs/integrations/hubspot.md"
last_verified_api_version: "1.18.0"
---

# 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.

_Last verified against API version 1.18.0._

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](https://signatureapi.com/docs/api/test-mode) (it starts with `key_test_`).
- The document you send, at a URL on a [supported host](https://signatureapi.com/docs/api/resources/documents/url#external-store), or [uploaded to SignatureAPI](https://signatureapi.com/docs/api/resources/uploads/create) first. The examples use a sample PDF.
- A HubSpot account with Data Hub Professional or Enterprise. HubSpot requires it for [custom code actions](https://developers.hubspot.com/docs/api/workflows/custom-code-actions) and for the [Send a webhook action](https://knowledge.hubspot.com/workflows/how-do-i-use-webhooks-with-hubspot-workflows).

## Send the envelope

1. **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.

2. **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.

3. **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`.

4. **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.

```javascript
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](https://knowledge.hubspot.com/workflows/set-when-a-webhook-is-received-workflow-triggers) lists the editions that include it.

1. **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.

2. **Register the URL in SignatureAPI**

   In the Dashboard, add a [webhook endpoint](https://signatureapi.com/docs/api/guides/how-to/set-up-webhooks) in test mode with the HubSpot URL. Subscribe to [`deliverable.generated`](https://signatureapi.com/docs/api/resources/events/deliverable-events#deliverablegenerated), which fires when the signed PDF is ready, and add the `hubspot` topic. The [`envelope.completed`](https://signatureapi.com/docs/api/resources/events/envelope-events#envelopecompleted) 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.

3. **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:

   1. **Method**: GET
   2. **URL**: `https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56`
   3. **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](https://signatureapi.com/docs/api/resources/deliverables/object#url), 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](https://signatureapi.com/docs/api/webhooks).

## Related

- [Create an envelope](https://signatureapi.com/docs/api/resources/envelopes/create): every field of the request body.
- [Organize with topics and metadata](https://signatureapi.com/docs/api/guides/how-to/organize-topics-metadata).
- [Make](https://signatureapi.com/docs/integrations/make), [Zapier](https://signatureapi.com/docs/integrations/zapier/http-recipe) and [n8n](https://signatureapi.com/docs/integrations/n8n) use the same request.

### Example: Deal contract

Sent when a HubSpot deal reaches the contract stage.

```http
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"
    }
  ]
}
```

Response 201 Created:

```json
{
  "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
}
```

Response 422 Unprocessable Content:

```json
{
  "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 that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
