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.

47 events covered

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

Signature header
X-HubSpot-Signature-v3

Format: <base64>

Scheme
HMAC-SHA256, base64
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.

How events are identified
subscriptionType field in the body
Body format
JSON

Content type: application/json.

Send timestamp
X-HubSpot-Request-Timestamp

Reject deliveries older than 5 minutes.

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.

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
Agent skill
npx skills add hookdeck/webhook-skills --skill hubspot-webhooks

Verify HubSpot webhooks →

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

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

HubSpot webhook best practices

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

contact.creation · .propertyChange · .deletion · .merge +3

7 2
company

company.creation · .propertyChange · .deletion · .associationChange +2

6 0
deal

deal.creation · .propertyChange · .deletion · .associationChange +2

6 0
line_item

line_item.creation · .deletion · .associationChange · .restore +2

6 0
object

object.creation · .deletion · .merge · .restore +2

6 2
ticket

ticket.creation · .deletion · .propertyChange · .associationChange +2

6 0
conversation

conversation.creation · .deletion · .privacyDeletion · .propertyChange +1

5 0
product

product.creation · .deletion · .restore · .merge +1

5 0

All 47 events →

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.

Not affiliated with HubSpot. Facts are compiled from public sources and linked inline.