Design a payment system: ledgers, webhooks, and idempotency
Payment
Guided ModeStep 4 β Webhook Handler for Gateway Callbacks
Request Flow
Gateway delivers callbacks via POST
When payment.succeeded fires, the gateway POSTs to your public webhook endpoint. A dedicated Webhook Handler receives this β it does nothing except validate and enqueue. It must respond with HTTP 200 within 5 seconds or the gateway retries.
HMAC signature validation
The Webhook Handler verifies the request signature using the shared HMAC-SHA256 secret. This prevents spoofed events injecting fake payment confirmations. Only after validation does it enqueue the event.
Idempotent enqueue
Gateways deliver webhooks at-least-once β you may receive payment.succeeded twice for the same charge. The Webhook Handler uses the event ID as a deduplication key before enqueuing, and the downstream worker handles the duplicate-safe settle step.
Why We Need This
A webhook endpoint must be dead-simple and respond in under 5 seconds β any processing beyond validation and enqueue risks a timeout and retry storm. The queue is the buffer that absorbs all complexity downstream.
Key Insight
Webhook handlers must be stateless, fast, and idempotent. Validate the signature, enqueue the event, return 200. Put all business logic in the downstream consumer, not the webhook endpoint itself.
Step 4 of 7
