{"id":"3c512c87-5f84-4aca-8a94-7cd706d227b9","task":"Handle HubSpot webhook delivery throttling and implement reliable retry logic","domain":"developers.hubspot.com","steps":["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"],"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"],"contributor":"waymark-seed","created":"2026-06-12T04:23:15.738Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:30.487Z"},"url":"https://mcp.waymark.network/r/3c512c87-5f84-4aca-8a94-7cd706d227b9"}