Webhook Integration That Survives Retries, Duplicates and Outages

What is webhook integration?

A webhook is an HTTP POST that one system sends to a URL you control when something happens: a payment succeeds, an order is created, a document is signed. Integration means receiving that POST, verifying it, and updating your own systems. It avoids polling an API every few minutes and gives you events almost immediately.

Typical webhook sources include Stripe, Shopify, GitHub, Twilio, Calendly, DocuSign and most modern SaaS platforms. Some providers, including Stripe, also let you send events to Amazon EventBridge or Azure Event Grid instead of an HTTP endpoint.

How do you verify that a webhook is genuine?

Anyone can send a POST to a public URL, so the handler must check the sender. Stripe signs each event and puts the signature in the Stripe-Signature header, and Shopify uses the X-Shopify-Hmac-Sha256 header. Both are HMAC signatures computed over the request body with a shared secret.

Verification needs the raw request body. Stripe warns that a framework that parses or reformats the body before you verify it will make verification fail. Stripe's libraries also compare the signed timestamp against the current time, with a default tolerance of five minutes, to stop replay of captured payloads.

Secrets should be stored per environment and rotated periodically. Stripe lets you keep an old secret active for up to 24 hours while you deploy the new one, so rotation does not require downtime.

What happens when an event arrives twice or out of order?

Duplicates and reordering are normal. Stripe states that endpoints may receive the same event more than once and that it does not guarantee delivery in the order events were generated. Its advice is to log the IDs of processed events and skip those already seen, and to avoid using the created timestamp to order events.

Shopify likewise points to the X-Shopify-Webhook-Id header for ignoring duplicate deliveries. A safe handler therefore stores the event ID in a table with a unique constraint, and processes the event inside the same database transaction as its side effects.

Version drift is another trap. Stripe notes that the API version set on your account when an event occurs determines the structure of the event, so upgrading your account's API version changes what future events look like. Pin the version your handler expects, and test an upgrade in a separate endpoint before switching production.

Why return a 200 quickly and process later?

Senders enforce timeouts. Stripe says to return a successful 2xx status before doing complex logic, and to process events through an asynchronous queue so a spike, such as many subscriptions renewing at the start of the month, does not overwhelm your servers.

The pattern is simple: verify the signature, write the raw event to a queue or table, return 200, then let a worker do the real job. Errors in the worker then never cause the sender to retry endlessly.

Watch out for frameworks that run CSRF protection on every POST. Stripe's documentation notes that the webhook route may need to be exempted from CSRF checks, since the sender has no token. Signature verification replaces that protection for this route.

Do you still need polling if you have webhooks?

Yes, as a safety net. Shopify tells developers not to rely on webhooks alone and to run reconciliation jobs that periodically fetch data. Stripe retries for up to three days, but a longer outage, a deleted endpoint or a bug in your handler can still leave gaps. A nightly job that compares recent records on both sides and repairs differences turns webhooks into a reliable system.

• Verify signatures against the raw body
• Deduplicate by event ID
• Acknowledge fast, process from a queue
• Reconcile on a schedule
• Alert when the failure count rises