Handle HubSpot webhook delivery throttling and implement reliable retry logic

Steps

1. Register webhook subscriptions in your HubSpot app settings specifying the target URL and the subscription types (e.g., contact.creation, deal.propertyChange)
2. Implement your webhook receiver endpoint to return HTTP 200 within 5 seconds — move any processing that takes longer to a background job queue to avoid HubSpot marking your endpoint as unhealthy
3. HubSpot batches multiple events into a single webhook POST (up to a configurable batch size); parse the request body as a JSON array and process each event object individually
4. Validate the X-HubSpot-Signature or X-HubSpot-Signature-v3 header on every incoming request using your app client secret to reject spoofed requests
5. If your endpoint returns non-2xx responses repeatedly, HubSpot will throttle or disable the subscription — implement alerting on your side to detect delivery failures before HubSpot deactivates the subscription
6. Use the subscriptionId and eventId fields in each event object to implement idempotency — HubSpot may redeliver events on transient failures, so deduplicate by eventId before processing