# 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](https://knowledge.hubspot.com/workflows/how-do-i-use-webhooks-with-hubspot-workflows) 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.

Agent skill: `npx skills add hookdeck/webhook-skills --skill hubspot-webhooks` ([details](https://hookdeck.com/webhooks/hubspot/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [HubSpot's official docs](https://developers.hubspot.com/docs/api-reference/legacy/webhooks/guide).

[Overview](https://hookdeck.com/webhooks/hubspot) · [Webhook events (47)](https://hookdeck.com/webhooks/hubspot/events) · [MCP events](https://hookdeck.com/webhooks/hubspot/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/hubspot/verify) · [Production guide](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/hubspot/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-HubSpot-Signature-v3` Format: <base64> | [HubSpot docs](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/request-validation) |
| Scheme | `HMAC-SHA256, base64` | [HubSpot docs](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/request-validation) |
| Signed material | `{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. | [HubSpot docs](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/request-validation) |
| How events are identified | `subscriptionType field in the body` | [HubSpot docs](https://developers.hubspot.com/docs/api-reference/latest/webhooks/guide) |
| Body format | `JSON` Content type: application/json. | [HubSpot docs](https://developers.hubspot.com/docs/api-reference/latest/webhooks/guide) |
| Send timestamp | `X-HubSpot-Request-Timestamp` Reject deliveries older than 5 minutes. | [HubSpot docs](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/request-validation) |
| Legacy signature | `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. | [HubSpot docs](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/request-validation) |
| Other headers | `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` | [Registry record](https://hookdeck.com/webhooks/hubspot.json) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill hubspot-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/hubspot/skill) |

[Verify HubSpot webhooks](https://hookdeck.com/webhooks/hubspot/verify)

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

## Setting up HubSpot webhooks

- New apps are project-based, since legacy public and private apps can no longer be created. Add a `*-hsmeta.json` file under `src/app/webhooks/` with your `targetUrl` and subscriptions. `crmObjects` takes the generic `object.*` types, while `legacyCrmObjects` and `hubEvents` take 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

- **Timeout:** 5 seconds. for the whole batch of notifications. [Guide](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** up to 10. over 24 hours, on connection failures, timeouts and any 4xx or 5xx. [Guide](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries:** not documented. HubSpot describes no resend, so reconcile from its APIs. [Guide](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not guaranteed. use `occurredAt` to tell when each event happened. [Guide](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

1. **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](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#timeouts)
2. **Duplicates that a simple key misses.** HubSpot can send a notification more than once, `eventId` isn't guaranteed to be unique, and `attemptNumber` changes on a retry. Deduplicate on `portalId`, `subscriptionId`, `eventId`, `objectId` and `occurredAt` together. [Handle duplicates](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#duplicates)
3. **Older changes overwriting newer ones.** HubSpot doesn't guarantee delivery order, so a stale `propertyValue` can arrive last. Compare `occurredAt` before you apply a change, or fetch the record's current state. [Handle ordering](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#ordering)
4. **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](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#retries)

From [Hookdeck's HubSpot guide](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts).

## HubSpot webhook best practices

- **[Verify the v3 signature](https://hookdeck.com/webhooks/hubspot/verify).** Check `X-HubSpot-Signature-v3` and the timestamp, because the older signature gives no replay protection.
- **[Return a 2xx within 5 seconds](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#timeouts).** The limit covers the whole batch, so queue the notifications and process them after you respond.
- **[Deduplicate each notification](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#duplicates).** `eventId` isn't guaranteed to be unique and `attemptNumber` changes on a retry, so build a key from several fields and leave `attemptNumber` out.
- **[Order by `occurredAt`](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#ordering).** Compare `occurredAt` before you apply a change, or fetch the record's current state.
- **[Return a 2xx for what you ignore](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#retries).** HubSpot retries any 4xx or 5xx, so rejecting an unwanted event earns up to 10 more deliveries.
- **[Skip your own writes](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts#choosing-events).** Check `changeSource` and `sourceId` so a change your integration made doesn't start a loop.

## Common HubSpot webhook events

### Contacts

- [contact.creation](https://hookdeck.com/webhooks/hubspot/events#contact.creation): A new contact is created
- [contact.propertyChange](https://hookdeck.com/webhooks/hubspot/events#contact.propertyChange): A subscribed property changes on a contact
- [contact.deletion](https://hookdeck.com/webhooks/hubspot/events#contact.deletion): A contact is deleted
- [contact.privacyDeletion](https://hookdeck.com/webhooks/hubspot/events#contact.privacyDeletion): A contact is deleted for privacy compliance

### Deals and companies

- [deal.creation](https://hookdeck.com/webhooks/hubspot/events#deal.creation): A new deal is created
- [deal.propertyChange](https://hookdeck.com/webhooks/hubspot/events#deal.propertyChange): A subscribed property changes on a deal
- [company.creation](https://hookdeck.com/webhooks/hubspot/events#company.creation): A new company is created
- [company.propertyChange](https://hookdeck.com/webhooks/hubspot/events#company.propertyChange): A subscribed property changes on a company

### Any object, generic format

- [object.creation](https://hookdeck.com/webhooks/hubspot/events#object.creation): A record of the subscribed object type is created
- [object.propertyChange](https://hookdeck.com/webhooks/hubspot/events#object.propertyChange): A subscribed property changes on a record of that type
- [object.associationChange](https://hookdeck.com/webhooks/hubspot/events#object.associationChange): An association on a record of that type is added or removed

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [contact](https://hookdeck.com/webhooks/hubspot/events#resource-contact) | 7 | 2 |
| [company](https://hookdeck.com/webhooks/hubspot/events#resource-company) | 6 | 0 |
| [deal](https://hookdeck.com/webhooks/hubspot/events#resource-deal) | 6 | 0 |
| [line_item](https://hookdeck.com/webhooks/hubspot/events#resource-line-item) | 6 | 0 |
| [object](https://hookdeck.com/webhooks/hubspot/events#resource-object) | 6 | 2 |
| [ticket](https://hookdeck.com/webhooks/hubspot/events#resource-ticket) | 6 | 0 |
| [conversation](https://hookdeck.com/webhooks/hubspot/events#resource-conversation) | 5 | 0 |
| [product](https://hookdeck.com/webhooks/hubspot/events#resource-product) | 5 | 0 |

[All 47 events](https://hookdeck.com/webhooks/hubspot/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/hubspot/events): Every covered HubSpot event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/hubspot/mcp-events): How an agent subscribes to HubSpot events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/hubspot/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/hubspot/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/hubspot/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill hubspot-webhooks`
---

Not affiliated with HubSpot. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/hubspot.json) · [Report a correction](https://hookdeck.com/contact)
