hubspot-webhook-handlers

What it does

Guides building HubSpot v3 webhook handlers that survive production failures. It covers: verifying HMAC-SHA256 signatures, using Redis SET NX for per-event deduplication, immediately acknowledging webhooks and processing in the background via a queue, routing permanently failed events to a dead-letter queue, guarding property-change event ordering, and handling list-membership subscriptions separately to avoid scope mismatches. It provides concrete code patterns and prerequisites for Node.js/TypeScript or Python environments and outlines how to wire these pieces together in production-grade webhook pipelines.

How it works

1. Signature verification: Uses HMAC-SHA256 over a string composed of the HTTP method, full request URI, raw body, and timestamp. Requires the raw body to be preserved (express.raw) and compares the computed hex digest against X-HubSpot-Signature-v3 in a timing-safe way. If headers are missing or timestamp is stale, responds with 403 and an error. On success, attaches parsed hubspot events to the request for downstream use.
2. Redis SET NX deduplication: Each event has a unique eventId. Performs a SET with NX and a 24-hour TTL to determine if an event is new. If the key already exists, the event is skipped; if new, the handler processes it and, on transient failure, deletes the key to allow retries.
3. Immediate ACK with async batch processing: For batch deliveries, responds with 200 immediately and enqueues each event to a BullMQ queue for background processing. The queue uses per-event jobs with dedup and retries configured.
4. Dead-letter queue: Uses BullMQ worker failed handling to route permanently failed jobs to a DLQ store, and emits an alert. Includes a replay pattern that re-enqueues DLQ items after clearing dedup keys.
5. Property change ordering guard: Applies property-change updates only if the incoming occurredAt is newer than the last applied version, stored in Redis, thus preventing older values from overwriting newer ones. Keeps a TTL to survive burst retries.
6. List-membership subscription: Documents that list-membership changes require separate subscriptions, since lifecyclestage changes delivered via contact.propertyChange do not include membership events.

When to use it

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 phrases include: 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.

What it can touch

• Redis (SET NX deduplication, property-change versioning, DLQ state)
• BullMQ queue (hubspot-events) for asynchronous processing
• Express raw body capture for signature verification
• Optional logging and alerting on failures
• Environment variables HUBSPOT_CLIENT_SECRET, Redis connection details

Caveats

• Requires proper middleware ordering to preserve raw body for signature verification.
• DLQ handling relies on BullMQ failure events and a Redis-backed store for DLQ records.
• List-membership events require separate subscription setup via HubSpot webhook API; lifecyclestage changes alone do not deliver list membership changes.
• Standardized error responses follow the explicit error keys used in the instructions (e.g., missing_signature, timestamp_out_of_window, invalid_signature, misconfigured_middleware).