HubSpot webhooks
HubSpot webhooks are signed JSON POSTs that HubSpot sends to your app's target URL when CRM records or conversation threads change in an account that installed the app.
These pages cover the events a HubSpot app subscribes to. Workflows are a separate feature: a workflow's Send a webhook action sends one record's data to a URL, with its own body and retry rules, and a webhook from another app can also trigger a workflow.
How HubSpot webhooks work
HubSpot pushes changes to you because polling scales poorly, especially for an app with many installs. You configure subscriptions once on the app, and they apply to every account that installs it. When a subscribed event happens, HubSpot sends a POST to your one target URL, with up to 10 requests in flight by default.
The body is an array of up to 100 notifications, so read every item. Each item's subscriptionType names the event: contact.creation in the classic format, or object.creation in the generic format, where objectTypeId says which object it applies to. Notifications are thin. They carry ids and, for a property change, propertyName and propertyValue, so fetch the record from the CRM API when you need more. Deliveries have no version header or field.
Key facts
{method}{uri}{body}{timestamp} The HTTP method, the full URI HubSpot called with the listed percent-encoded characters decoded, the body as sent, then the X-HubSpot-Request-Timestamp header, with no separators.
X-HubSpot-Signature, X-HubSpot-Signature-Version A plain SHA-256 hex digest, not an HMAC: secret + body for v1, secret + method + URI + body for v2, as named by X-HubSpot-Signature-Version.
x-hubspot-client-ip, x-hubspot-correlation-id, x-hubspot-request-timestamp, x-hubspot-requesting-chain-bin, x-hubspot-signature-version, x-hubspot-timeout-millis, x-trace Setting up HubSpot webhooks
- New apps are project-based, since legacy public and private apps can no longer be created. Add a
*-hsmeta.jsonfile undersrc/app/webhooks/with yourtargetUrland subscriptions.crmObjectstakes the genericobject.*types, whilelegacyCrmObjectsandhubEventstake the classic ones. - Existing legacy apps keep their Webhooks settings: enter a Target URL, create subscriptions, then check they're active. Each property change subscription names one property, and your app needs the matching read scope, such as
crm.objects.contacts.read. - Test from a legacy app's subscription details panel, where Test sends a sample payload to your URL, or tunnel real events to localhost with the Hookdeck CLI:
hookdeck listen 3000 hubspot --path /webhooks/hubspot. - HubSpot documents no way to resend a notification. Its journal API returns the past 3 days of events for subscriptions you create through that API.
Delivery behaviour
Known failure modes
From Hookdeck's HubSpot guide →-
A slow batch times out as a whole
HubSpot allows five seconds for a response to a batch of up to 100 notifications, then retries. Respond first and process the items from a queue.
Handle timeouts → -
Duplicates that a simple key misses
HubSpot can send a notification more than once,
Handle duplicates →eventIdisn't guaranteed to be unique, andattemptNumberchanges on a retry. Deduplicate onportalId,subscriptionId,eventId,objectIdandoccurredAttogether. -
Older changes overwriting newer ones
HubSpot doesn't guarantee delivery order, so a stale
Handle ordering →propertyValuecan arrive last. CompareoccurredAtbefore you apply a change, or fetch the record's current state. -
A 4xx gets retried
App webhooks retry on any 4xx or 5xx, up to 10 times over 24 hours, so a 400 for an event you don't want brings it back. Return a 2xx for anything you choose to ignore.
Retries and lost events →
HubSpot webhook best practices
- Verify the v3 signature.
Check
X-HubSpot-Signature-v3and the timestamp, because the older signature gives no replay protection. - Return a 2xx within 5 seconds. The limit covers the whole batch, so queue the notifications and process them after you respond.
- Deduplicate each notification.
eventIdisn't guaranteed to be unique andattemptNumberchanges on a retry, so build a key from several fields and leaveattemptNumberout. - Order by `occurredAt`.
Compare
occurredAtbefore you apply a change, or fetch the record's current state. - Return a 2xx for what you ignore. HubSpot retries any 4xx or 5xx, so rejecting an unwanted event earns up to 10 more deliveries.
- Skip your own writes.
Check
changeSourceandsourceIdso a change your integration made doesn't start a loop.
Common HubSpot webhook events
Contacts
contact.creation | A new contact is created |
contact.propertyChange | A subscribed property changes on a contact |
contact.deletion | A contact is deleted |
contact.privacyDeletion | A contact is deleted for privacy compliance |
Deals and companies
deal.creation | A new deal is created |
deal.propertyChange | A subscribed property changes on a deal |
company.creation | A new company is created |
company.propertyChange | A subscribed property changes on a company |
Any object, generic format
object.creation | A record of the subscribed object type is created |
object.propertyChange | A subscribed property changes on a record of that type |
object.associationChange | An association on a record of that type is added or removed |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
contact | 7 | 2 |
company | 6 | 0 |
deal | 6 | 0 |
line_item | 6 | 0 |
object | 6 | 2 |
ticket | 6 | 0 |
conversation | 5 | 0 |
product | 5 | 0 |
In this hub
| Webhook events → | Every covered HubSpot event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to HubSpot events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill hubspot-webhooks |
Keep a slow handler from sending HubSpot batches back for retry.
Hookdeck Event Gateway accepts each HubSpot delivery, verifies its signature, queues it and retries to your service on your schedule, and keeps a log of every attempt so you can replay what failed.