Register webhook subscriptions in your HubSpot app settings specifying the target URL and the subscription types (e.g., contact.creation, deal.propertyChange)
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
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
Validate the X-HubSpot-Signature or X-HubSpot-Signature-v3 header on every incoming request using your app client secret to reject spoofed requests
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
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
Known gotchas
HubSpot webhook delivery order is not guaranteed even within a single subscription — do not assume events arrive in chronological sequence; use the occurredAt timestamp on each event to reorder if sequence matters
HubSpot throttles webhook delivery to roughly 100 concurrent connections per app; high-volume portals generating thousands of events per second will see significant delivery lag — design for eventual consistency rather than real-time processing
The X-HubSpot-Signature-v3 validation requires hashing the concatenation of the client secret, HTTP method, full URL (including query string), and raw request body — using the parsed/decoded body instead of the raw bytes is the most common validation failure
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp