What a Webhook Receiver Should Do Before It Says 200
Short answer: A webhook receiver should do only four quick things before replying with a success status: check the sender's signature, store the raw event, note whether it has been seen before, and put a job on a queue. Everything slow, such as emailing a customer, updating stock or calling another service, happens after the reply, in a worker. Senders expect an answer within seconds and retry when they do not get one, so a receiver that does the whole job inline will time out, get retried, and process the same event twice.
The anatomy of a well-behaved receiver
Picture a small online shop in Brisbane. Its payment provider sends a message each time a payment succeeds. The shop's endpoint is a single web address. What happens inside that address decides whether the shop ships one parcel or two.
Stage 1: prove the message is genuine
Anyone who learns your endpoint address can post to it. Providers therefore sign each delivery, and the receiver must verify the signature against a secret only the two of you know. The Stripe webhooks documentation explains the pattern for its own events, and most other providers follow the same idea: a header holding a signature and a timestamp.
Two details trip people up. The signature is computed over the exact raw bytes of the body, so if your framework parses and re-serialises the JSON before you verify, the check fails. And the timestamp lets you reject very old messages, which blocks someone replaying a captured request. Reject failed checks with a client error and do no further work.
Stage 2: write the raw event down
Insert the event, unchanged, into a table with its identifier, type, received time and a status of "pending". This single write is your safety net. If everything after it breaks, you still hold what was sent and can replay it, and you can answer a provider support person who asks what you received.
Stage 3: spot repeats
Providers guarantee delivery at least once, not exactly once. A network blip, a slow reply or a manual resend produces the same event again. Give the stored event identifier a unique constraint. If the insert fails because it already exists, you have seen it: reply success and stop. This is cheaper and more reliable than trying to detect duplicates by inspecting order contents later.
Stage 4: queue it and answer
Add a job reference to a queue (a database table polled by a worker is perfectly good at small scale) and return a success status immediately. The whole receiver should finish in a fraction of a second.
What belongs after the reply
The worker picks pending events and does the real work, one at a time per order or customer so two events for the same order cannot race each other:
- Mark the order paid and reduce stock.
- Send the confirmation email.
- Create the invoice in the accounts package.
- Notify the warehouse.
If a step fails, the worker retries on its own schedule, with growing waits, and after a set number of attempts moves the event to a "needs a person" list. The provider sees a success at stage 4 and never knows about your internal retries, which keeps the two retry systems from fighting.
Order is not guaranteed
Events may arrive out of order. An "order updated" message can reach you before "order created". Two ways to cope:
- Treat each event as a hint and fetch the latest state from the provider's API in the worker, rather than trusting the event body as the final truth.
- Compare version numbers or timestamps in the event and ignore anything older than what you already hold.
Option 1 is simpler and robust for small systems, provided you respect the provider's rate limits.
Status codes the sender reads
| Your reply | What most senders do |
|---|---|
| 2xx within the time limit | Mark delivered, stop retrying |
| 4xx for a bad signature | Treat as your decision; some give up, some retry |
| 5xx or no answer in time | Retry later, often for days, and may disable the endpoint after repeated failures |
Check your provider's documentation for the exact time limit and retry schedule, because they differ and change. As of November 2026 the details are on each vendor's own docs page, so confirm there instead of trusting a number from an article.
Checks to run before going live
- [ ] Send a test event and confirm the signature check passes, then tamper with one character and confirm it fails.
- [ ] Post the same event twice and confirm only one order changes.
- [ ] Stop the worker, send three events, restart it, and confirm all three are processed.
- [ ] Make the email step fail on purpose and confirm the event ends up on the "needs a person" list rather than vanishing.
- [ ] Confirm the receiver replies quickly even when the accounts package is down.
- [ ] Check that logs do not print the signing secret or full card-related fields.
FAQ
Should the endpoint return 200 even if my processing later fails?
Yes, once the event is safely stored. The reply means "received", not "fully handled". Failure handling belongs to your worker.
What if the provider disables my endpoint?
Fix the cause, re-enable it, then ask the provider for a replay of missed events or fetch recent events through their API and feed them through the same pipeline.
Can a no-code tool be the receiver?
Often, yes. Many automation platforms give you a catch URL and queue behaviour out of the box. You still need to think about signatures, duplicates and what happens when a later step fails.
How long should we keep stored events?
Long enough to investigate disputes, for example a few months, then purge. Raw events can contain personal data, so apply the same retention thinking as for the rest of your records.
If your shop or booking system is double-processing events or missing them, send us the details and we will review the receiver with you.