Agent skill · software engineering · jeremylongshore
hubspot-webhook-handlers
Build and harden HubSpot v3 webhook handlers that survive production: HMAC-SHA256 signature verification, Redis SET NX deduplication, async batch processing with immediate 200 ACK, dead-letter queuing for permanent failures, and event-ordering guards for property-change streams. Use when implementing HubSpot webhooks for the first time, hardening an existing handler against retry storms or duplicate processing, debugging signature verification failures, or designing a reliable event pipeline for contact, company, or deal change events. Trigger with "hubspot webhook", "hubspot signature verification", "hubspot webhook dedup", "hubspot webhook retry storm", "hubspot event handler", "hubspot property change webhook", "hubspot list membership webhook", "hubspot dead letter queue".
Why this skill is useful
Adds executable scripts for HubSpot webhook handling that include HMAC verification, deduplication, and async processing patterns not commonly found in public documentation.
What it needs
Requires bullmq, express, node, redis installed locally. Requires hubspot account access. About 10k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
HubSpot Webhook Handlers Overview Receive and process HubSpot webhook events reliably at production scale. This is not a walkthrough for getting your first event — it is the handler code your integration runs when HubSpot delivers 100 events in a single payload at 2am, when a misconfigured proxy silently strips your signature header, when a 3-day outage causes events to arrive in a burst after recovery, and when a rapid sequence of property updates arrives reversed because HubSpot sends in delivery order rather than chronological order. The six production failures this skill prevents: 1. Signature verification bypass — skipping or misconfiguring the HMAC-SHA256 check on X-HubSpot-Signature-v3 allows any party to send spoofed webhook payloads to your endpoint. One misconfigured load balancer or proxy that strips the X-HubSpot-Signature-v3 header silently disables all security — your handler returns 200 to unauthenticated requests without knowing it. 2. Duplicate delivery — HubSpot retries unacknowledged webhooks (non-200 response or timeout) for up to 3 days with exponential backoff. If your handler crashes after processing but before responding, the same contact-update event creates duplicate CRM mutations downstream. Redis SET NX on the event ID is the reliable guard. 3. No replay API — events are permanently lost after the 3-day retry window — if your handler is down for more than 3 days, HubSpot drops those events permanently. There is no replay endpoint. Dead-letter queues and recovery runbooks are your only mitigation. 4. Batch event explosion — a single webhook delivery contains up to 100 events. Synchronous processing of all 100 within the HTTP request context times out (HubSpot timeout: 5 seconds) and returns 5xx, which triggers a retry storm. The correct pattern is to ACK immediately with 200, enqueue the batch, and process asynchronously. 5. Property change ordering — HubSpot sends contact.propertyChange events in delivery order, not chronological order. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/hubspot-webhook-handlers