Skip to content

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

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

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.

SettingValue
Method GET
URL https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56
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.