Webhooks are inherently chaotic. They rely on the open internet, which guarantees packet loss, network latency, and DNS resolution failures. Building a resilient webhook consumer requires adhering to four non-negotiable architectural principles.
Most providers (Stripe, GitHub) expect an HTTP 200 OK within 3 to 5 seconds. If you query a database, generate a PDF invoice, and send an email synchronously during the webhook request, you will inevitably hit timeouts. The provider will assume the webhook failed and trigger a retry storm.
The Solution:
return res.sendStatus(200)).Network failures happen. A provider might send the webhook, your server processes it successfully, but the TCP connection drops before your 200 OK reaches the provider. The provider will send the exact same event again.
The Solution:
Design your system so that applying the same event multiple times has the exact same state outcome as applying it once. Store the provider's unique event.id in your database. Before processing, perform a fast indexed lookup to see if the event has already been consumed.
Webhook endpoints must be publicly accessible on the internet, which means they are susceptible to port scanners, bots, and malicious actors trying to forge "payment successful" payloads.
Never trust the payload until you verify the HMAC signature. Hookmetry's Endpoint infrastructure can offload this verification for you, dropping unauthenticated requests at our Edge layer before they reach your servers.
Was this page helpful?
Your feedback helps us improve the docs.