Webhooks API

• You must create a public app to use webhooks by subscribing to the events you want to be notified about, and by specifying a URL to send those notifications.
• You must deploy a publicly available and secure (HTTPS) endpoint for that URL that can handle the webhook payloads specified in this documentation.

​

Scopes

• If you’re creating subscriptions in the settings UI of your public app, you’ll be prompted to add the required scope in the Create new webhook subscriptions panel before you finish creating your subscription.
• If you’re creating a subscription by making a POST request to the /webhooks/v3/{appId}/subscriptions endpoint, the response will include an error that will provide the name of the scope you’ll need to configure in the settings UI of your public app.
• If your app is already using webhooks, you won’t be able to remove any scopes required by active webhook subscriptions without first pausing and removing the subscriptions.
• You can review the scopes required for each webhook subscription type in the table below.

​

Webhook settings

​

Manage settings in your developer account

• In your developer account, in the left sidebar, click Apps, then click the name of your app you want to manage.

• In the left sidebar menu, navigate to Webhooks.
• In the Target URL field, enter the URL that HubSpot will make a POST request to when events trigger.
• Use the Event throttling setting to adjust the maximum number of events HubSpot will attempt to send.

• Click Save.

​

Manage settings via API

{
  "targetUrl": "https://www.example.com/hubspot/target",
  "throttling": {
    "maxConcurrentRequests": 10
  }
}

​

Webhook subscriptions

• When associating two contacts, a subscription to contact.associationChange will fire two events, representing contact 1 to contact 2 and contact 2 to contact 1.
• When associating a company, if you have two webhook subscriptions contact.associationChange and company.associationChange, you will receive two events. These will represent contact 1 to company 1 and company 1 to contact 1.

• num_unique_conversion_events
• hs_lastmodifieddate

• assignedTo: the conversation thread has been reassigned or unassigned. If the thread was reassigned, the propertyValue will be an actor ID in the webhooks payload; if unassigned, it will be empty.
• status: the status of the conversation thread has changed. In the webhooks payload, the propertyValue will either be OPEN or CLOSED.
• isArchived: the conversation thread has been restored. The propertyValue in the webhooks payload will always be FALSE.

​

Create subscriptions in your developer account

• In your HubSpot developer account, navigate to the Apps dashboard.
• Click the name of an app.
• In the left sidebar menu, navigate to Webhooks.
• Click Create subscription.
• In the right panel, click the Which object types? dropdown menu and select the objects you want to create a subscription for.
• Click the Listen for which events? dropdown menu and select the event types.

• If you’re creating a subscription for property change events, click the Which properties? dropdown menu and select the properties to listen for.

• Click Subscribe.

• In the Event subscriptions section, hover over the object type and click View subscriptions.
• Select the checkbox next to the event, then in the table header click Activate.

​

Manage subscriptions via API

​

Get subscriptions

[
  {
    "id": 25,
    "createdAt": 1461704185000,
    "createdBy": 529872,
    "eventType": "contact.propertyChange",
    "propertyName": "lifecyclestage",
    "active": false
  },
  {
    "id": 59,
    "createdAt": 1462388498000,
    "createdBy": 529872,
    "eventType": "company.creation",
    "active": false
  },
  {
    "id": 108,
    "createdAt": 1463423132000,
    "createdBy": 529872,
    "eventType": "deal.creation",
    "active": true
  }
]

​

Create a new subscription

{
  "eventType": "company.propertyChange",
  "propertyName": "companyname",
  "active": false
}

​

Update a subscription

​

Delete a subscription

​

Webhook payloads

[
  {
    "objectId": 1246965,
    "propertyName": "lifecyclestage",
    "propertyValue": "subscriber",
    "changeSource": "ACADEMY",
    "eventId": 3816279340,
    "subscriptionId": 25,
    "portalId": 33,
    "appId": 1160452,
    "occurredAt": 1462216307945,
    "eventType": "contact.propertyChange",
    "attemptNumber": 0
  },
  {
    "objectId": 1246978,
    "changeSource": "IMPORT",
    "eventId": 3816279480,
    "subscriptionId": 22,
    "portalId": 33,
    "appId": 1160452,
    "occurredAt": 1462216307945,
    "eventType": "contact.creation",
    "attemptNumber": 0
  }
]

​

Testing webhooks

​

Private apps

• In your HubSpot account, click the Settings icon in the top right.
• In the left sidebar menu, navigate to Integrations > Private apps.
• Click the name of your private app.
• Click the Webhooks tab.
• Click the record type of a webhook subscription (e.g., Contact) to expand the section, hover over a specific subscription type, then click View details.
• In the right panel, under Test this subscription, confirm the Test URL is correct, then click Test.

​

Public apps

• In your developer account, in the left sidebar menu, click Apps.
• Click the name of your app.
• Under Features, click Webhooks.
• Hover over the record type of a webhook subscription, then click Details.
• In the right panel, under Test this subscription, confirm the Test URL is correct, then click Test.

​

Privacy compliant contact deletions

• A privacy deletion event will also trigger the contact deletion event, so you will receive two notifications if you are subscribed to both events.
• These notifications will not necessarily be sent in any specific order or in the same batch of messages. You will need to use the object ID to match the separate messages.

​

Security

​

Retries

• Connection failed: HubSpot cannot open an HTTP connection to the provided webhook URL.
• Timeout: your service takes longer than five seconds to send back a response to a batch of notifications.
• Error codes: your service responds with any HTTP status code (4xx or 5xx).

​

Limits

{
  "status": "error",
  "message": "Couldn't create another subscription. You've reached the maximum number allowed per application (1000).",
  "correlationId": "2c9beb86-387b-4ff6-96f7-dbb486c00a95",
  "requestId": "919c4c84f66769e53b2c5713d192fca7"
}