HubSpot webhooks in production: duplicates, ordering, retries and timeouts
This guide covers the problems HubSpot webhooks cause in production and how to handle each one. What HubSpot sends and how it's signed is on the HubSpot webhooks overview, every event type is on HubSpot webhook events, and signature verification code is on Verify HubSpot webhooks.
It's about the subscriptions a HubSpot app makes, whether they use classic types like contact.creation or generic ones like object.creation. A workflow's Send a webhook action behaves differently, and Retries says how.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 2xx within 5 seconds; process the batch in a background job | Accepts the delivery at once, then queues it for your service |
| Duplicates | Deduplicate per notification, without attemptNumber; expect paired events | Drops identical deliveries before they reach your handler |
| Ordering | Compare occurredAt; fetch current state when in doubt | Logs every event and attempt, so you can see arrival order when debugging |
| Retries | Return a 2xx for what you ignore; reconcile after an outage | Accepts deliveries while your service is down and replays them |
| Choosing events | Subscribe by property; skip your own writes; route by account | Filters and routes events by header or body |
| Testing | Use HubSpot's Test button and forward real events to localhost | Forwards to localhost and replays past events |
| Other limits | Plan for cached settings, thin payloads and API rate limits | Lets you change destinations without touching HubSpot |
HubSpot webhook timeouts and slow handlers
Return a 2xx within five seconds, then do the work in a background job.
Why it happens: HubSpot treats a response that takes longer than five seconds as a failure and retries. That limit covers a whole request, which can hold up to 100 notifications, so work that's fine for one event can miss it for a batch. HubSpot's own example is a bulk import, where it sends the notifications for imported records in batches. Cold starts on serverless functions use up part of the five seconds too.
Fix it in your handler:
- Verify the signature and return 200 straight away.
- Push each item in the array onto a queue (SQS, RabbitMQ or Redis) and process it in a worker. See why to process webhooks asynchronously.
- Keep database writes and calls to other services out of the request path.
- Treat each item separately, so one bad notification doesn't fail the rest of the batch.
With Event Gateway: Hookdeck accepts each HubSpot delivery immediately, then queues it and delivers to your service with a delivery timeout you can set. Your handler can take as long as it needs without failing a HubSpot delivery.
Duplicate HubSpot webhooks
HubSpot can send the same notification more than once, and some actions send two different notifications. Deduplicate each item in the array, using a key that stays the same across retries.
Why it happens: HubSpot doesn't guarantee a single notification per event, though it says duplicates should be rare. Three things make the obvious fix fail:
eventIdis not guaranteed to be unique, so it can't be the whole key.attemptNumbergoes up on each retry, so a key that includes it never matches the earlier attempt.- Some actions produce two real notifications. Every
associationChangesubscription fires for both sides of the association, a primary association can also create a non-primary one, and acontact.privacyDeletionalso triggerscontact.deletion.
Fix it in your handler:
- Build a key from
portalId,subscriptionId,eventId,objectIdandoccurredAt, and leave outattemptNumber. For an association change, which hasfromObjectIdandtoObjectIdinstead ofobjectId, use those. - Store the keys with a unique constraint, or in a cache whose TTL outlasts HubSpot's 24-hour retry window.
- Make every handler idempotent: the same result however many times it runs.
- Match a privacy deletion to its deletion by object id. They can arrive in any order and in different batches.
async function processNotification(item) {
const target = item.objectId ?? `${item.fromObjectId}-${item.toObjectId}`;
const key = `hubspot:${item.portalId}:${item.subscriptionId}:${item.eventId}:${target}:${item.occurredAt}`;
if (await redis.exists(key)) return;
await handle(item);
await redis.set(key, '1', { EX: 172800 }); // 48 hours, past the 24-hour retry window
}
With Event Gateway: Hookdeck deduplicates deliveries on the fields you choose, so an identical request sent twice is dropped before it reaches you. HubSpot doesn't say a retried batch holds the same notifications, so keep the check per notification in your handler as well.
Out-of-order HubSpot webhooks
HubSpot doesn't guarantee delivery order. Use occurredAt to tell when each event happened, or fetch the record's current state.
Why it happens: Notifications are batched and sent concurrently, and a retry can arrive long after a newer change. When a contact's property changes twice in quick succession, the older propertyValue can land last and overwrite the newer one. For more on the general problem, see Webhook Ordering: Why It's Hard and How to Handle It.
Fix it in your handler:
- Store the last
occurredAtyou applied for each record and property, and skip anything older. - Fetch the record from the CRM API when the current state matters more than the history.
- Write state changes so they tolerate notifications in any order, such as a deletion arriving before a property change on the same record.
async function applyPropertyChange({ objectId, propertyName, propertyValue, occurredAt }) {
const key = `hubspot:last:${objectId}:${propertyName}`;
const last = await redis.get(key);
if (last && Number(last) > occurredAt) return;
await updateRecord(objectId, propertyName, propertyValue);
await redis.set(key, occurredAt);
}
With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.
HubSpot webhook retries and lost events
HubSpot retries a failed delivery up to 10 times over 24 hours. Return a 2xx for anything you don't want back, and reconcile after any longer outage.
Why it happens: HubSpot retries when it can't open a connection, when your service takes longer than five seconds, and on any 4xx or 5xx. So a 400 for an event you've chosen to reject is treated the same as an outage. Delays vary, with some randomization so that a large failure isn't all retried at once. attemptNumber in each notification starts at 0 and says which attempt you're looking at. HubSpot describes no way to change this schedule or to resend a notification, and doesn't say what happens after the last retry.
Workflow webhooks differ. A workflow's Send a webhook action retries for up to three days, starting a minute after the failure, with up to eight hours between tries. It stops on a 4xx, apart from a 429, where it respects Retry-After, which HubSpot records in milliseconds.
Fix it in your handler:
- Return a 2xx for notifications you ignore, and handle bad data in your own code.
- Reserve 5xx responses for real failures that a retry could fix, and alert when
attemptNumberclimbs. - Keep a log of what you receive, so you can see gaps. Legacy private apps also have a Logs tab that lists each trigger and your endpoint's response, filterable by subscription type and status.
- After an outage longer than 24 hours, reconcile from the webhook journal API, which holds 3 days of events for subscriptions created through that API, or from the CRM APIs.
With Event Gateway: Hookdeck captures every HubSpot delivery while your services are down, so HubSpot's deliveries succeed while you recover. Failed events can be retried automatically, manually or in bulk once you're back. For the general pattern, see dead letter queues.
Choosing which HubSpot events to listen to
Subscribe only to the events and properties you process, and make sure your own writes don't start a loop.
Why it matters: Subscriptions are set on the app and apply to every account that installs it, so you can't turn one on for some accounts only. A property change subscription names one property, which keeps volume down, but hs_lastmodifieddate and num_ aren't available. If an account doesn't have the property you name, you get no webhooks from that account for it. The full list is on HubSpot webhook events. Generic object.* subscriptions cover objects the classic types don't, such as calls, invoices and tasks, while contact.privacyDeletion and conversation.* are only available in the classic format.
HubSpot also reports changes your own integration makes, so an update you write back can fire another notification.
Fix it in your handler:
- List the events and properties your code handles and subscribe to exactly those.
- Compare
changeSource, andsourceIdwhere present, with what your own writes produce. HubSpot doesn't publish a list of values, saying only that they match the change sources in contact property histories, so log a few of your own writes first. - Route or skip by
portalIdin your handler if some accounts shouldn't be processed.appIdtells you which app it was if several share a URL. - For generic subscriptions, read
objectTypeIdbefore you act, becausesubscriptionTypedoesn't say which object it is.
With Event Gateway: Hookdeck filters and routes events by header or body, so one HubSpot target URL can feed several services.
Testing and debugging HubSpot webhooks locally
Send HubSpot's sample payload to your URL to check it responds, then forward real events to your machine to see what they look like.
Why it's awkward: HubSpot needs a public HTTPS URL, and its Test button sends a listed sample payload, not a real event. Bulk imports, merges and association changes behave differently from a single record change, so a passing test doesn't tell you much about those.
How to test it:
- On a legacy app, open a subscription's details panel and click Test, then read your endpoint's response at the bottom of the panel.
- Use a test account and trigger real events, such as creating a contact, to see real payloads and headers. HubSpot webhook events has sample payloads to start from, and Hookdeck Inspect shows requests without any setup.
- Allow up to five minutes after changing the URL or a subscription before you expect it to apply.
- Try the cases that break handlers: a bulk import, a merge, an association change, a privacy deletion, and a retry caused by returning an error on purpose.
With Event Gateway: The Hookdeck CLI receives webhooks on your machine without a public server, and you can replay past events with one click.
Other HubSpot webhook limits
Plan for cached settings, concurrency, thin payloads and API rate limits before they reach production.
Settings are cached for up to five minutes. A new URL, concurrency limit or subscription can take that long to apply. Keep the old endpoint running for at least five minutes after you move.
Concurrency. HubSpot makes up to 10 requests at a time for each account that installed your app, and each holds up to 100 notifications. Through the API, maxConcurrentRequests must be a number greater than five. Size your handler for that peak.
Thin payloads. A notification has ids and the changed value, not the whole record. You usually fetch the rest from the CRM API. The webhook POSTs themselves don't count against your API limits, but those fetches do: 110 requests per 10 seconds per installed account for a marketplace-distributed app, and 100 or 190 per 10 seconds per app for a privately distributed one, depending on tier. Cache what you can and queue the calls.
1000 subscriptions per app. A request beyond that gets a 400 response.
Migrating apps. Legacy public and private apps can't be created any more, though existing ones still work. Project-based apps define subscriptions in a config file, and the generic format is their standard.
With Event Gateway: Your HubSpot target URL stays on Hookdeck, so you can change where events go without waiting on HubSpot's cached settings. Hookdeck absorbs spikes in its queue and delivers at a rate you configure, which keeps the API calls your handlers make below HubSpot's limits.
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.