Skip to main content

Receive HubSpot webhooks

Guides

HubSpot signs webhooks with your app's client secret. It uses three signature versions, so DataLug has an option for each:

HubSpot sendsSignature setting
X-HubSpot-Signature-v3HubSpot app webhook
X-HubSpot-Signature with X-HubSpot-Signature-Version: v1HubSpot private or legacy app (v1)
X-HubSpot-Signature with X-HubSpot-Signature-Version: v2HubSpot workflow webhook

Receive a webhook from any system covers the shared settings.

App webhook subscriptions​

  1. In Manage Account > Webhooks, select New webhook, enter a name and set Signature to HubSpot app webhook.
  2. Paste your HubSpot app's client secret into Client secret and press Create webhook.
  3. In HubSpot, open Development > Legacy apps, select your app and open Webhooks.
  4. Paste the DataLug webhook URL into Target URL and save.

DataLug checks the X-HubSpot-Signature-v3 header over the request method, the full webhook URL, the body and the X-HubSpot-Request-Timestamp header, and refuses a request more than 5 minutes old.

Private and legacy app webhooks (v1)​

Use this when your app's webhook requests carry X-HubSpot-Signature-Version: v1.

  1. In Manage Account > Webhooks, select New webhook, enter a name and set Signature to HubSpot private or legacy app (v1).
  2. Paste the app's client secret into Client secret and press Create webhook. For a private app, the client secret is on the app's Auth tab.
  3. In HubSpot, open Development > Legacy apps, select your app and open Webhooks.
  4. Select Edit webhooks, paste the DataLug webhook URL into Target URL and save.

DataLug checks the X-HubSpot-Signature header over the client secret and the body. A v1 signature has no timestamp, so a repeated request is refused by its event id instead.

Workflow webhook actions​

  1. In Manage Account > Webhooks, select New webhook, enter a name and set Signature to HubSpot workflow webhook.
  2. Paste the client secret of the app that signs the request into Client secret and press Create webhook.
  3. In the HubSpot workflow, add the Data ops > Send a webhook action and paste the DataLug webhook URL into its webhook URL field.
  4. Select Include request signature in header and enter the app ID of the app whose client secret you pasted in step 2.

DataLug checks the X-HubSpot-Signature header with X-HubSpot-Signature-Version: v2, over the client secret, the request method, the full webhook URL and the body.

The webhook URL must match exactly

HubSpot signs the URL it sends to. Paste the webhook URL exactly as the card shows it.

Batches​

HubSpot sends several events in one request. Each event becomes its own delivery and its own run, and HubSpot gets one 200 for the request.

Duplicates​

Each event's subscription id, event id and time together are its event id: an event that arrives again, alone or in a later batch, runs once, and an event repeated inside one batch runs once. A request from a workflow action has no event id; it is a duplicate only when its body repeats within 24 hours.

Changing the client secret​

Open the webhook's Settings, enter the new secret in Client secret and press Save settings. The old secret keeps working for 24 hours.