A webhook is an untrusted HTTP request that says something happened. Treat it like a public endpoint: verify the signature, make it idempotent, respond quickly and process the work asynchronously.
Key takeaways
- Verify the signature against the raw body before parsing JSON.
- Use the provider's event ID as an idempotency key.
- Return a 2xx quickly; move slow work to a queue.
- Prefer the simplest boundary that keeps data and authorisation on the server.
What matters in practice
- Expect duplicates, retries and out-of-order delivery.
- Log the event ID, type and outcome for replay and debugging.
How to implement it
- Create a dedicated route. Keep it separate from your UI and public API.
- Read the raw body. Do not let a framework parse it before verification.
- Verify the signature. Use the provider's SDK or documented algorithm.
- Deduplicate. Store the event ID and skip it if already processed.
- Queue the work. Return 2xx, then process the event with retries.
- Monitor and replay. Alert on failures and provide a safe replay path.
A working example
export async function POST(request: Request) {
const raw = await request.text();
const signature = request.headers.get("x-signature");
if (!verify(raw, signature, process.env.WEBHOOK_SECRET!)) {
return new Response("Invalid signature", { status: 401 });
}
const event = JSON.parse(raw);
await queue.enqueue("webhook", { id: event.id, type: event.type, payload: event });
return Response.json({ received: true });
}
Production checklist
| Area | Check |
|---|---|
| Signature | Raw body and the current secret |
| Idempotency | Event ID stored with a unique constraint |
| Retries | Queue with backoff and a dead-letter path |
| Ordering | Version or timestamp check where order matters |
| Observability | Event ID, type, latency and outcome |
| Security | Allowlist, rate limit and secret rotation |
Common mistakes
- Parsing JSON before verifying the signature.
- Returning 200 before the work is durable.
- Processing the same event twice and double-charging or double-emailing.
- Assuming events arrive in order.
When this is the wrong tool
Every tool has a boundary. If the team is small, the use case is simple and the operational cost is high, a simpler stack may be better. The right choice is the one you can debug, secure and hand over without the original author.
Rollout plan
- Prove one slice. Use Webhooks for one real route or feature, not the whole product.
- Set the boundary. Write down what stays on the server, what runs on the client and how data crosses the boundary.
- Add the safety net. Types, validation, tests and error handling around the new slice.
- Measure. Check bundle size, latency, error rate and the developer experience before expanding.
- Document and hand over. Record the pattern, the pitfalls and the version constraints.
Testing strategy
| Layer | What to test | Why |
|---|---|---|
| Types | Strict compile and no unjustified any | Catches contract drift early |
| Unit | Pure logic, validation and state transitions | Fast feedback |
| Integration | API, database and auth boundaries | Most production failures live here |
| End-to-end | The critical user journey | Proves the wiring |
| Operations | Logs, errors, retries and rollback | A release is not finished at deploy |
Operational checklist
- Pin the runtime and dependency versions; test upgrades in a branch.
- Keep secrets on the server and validate every external payload.
- Add structured logs with a request ID, but never log tokens or personal data.
- Set a performance or bundle budget and check it in CI.
- Write a short runbook for the most likely failure.
Frequently asked questions
The provider needs a quick acknowledgement so it does not retry. Put the event in a durable queue, then process it with retries. If the queue write fails, return a 5xx so the provider retries.
Use the provider's CLI or a tunnel, send real events, and test duplicate delivery, invalid signatures and slow processing. Keep a replay tool for production incidents.
The same event can be processed more than once without changing the result. Store the event ID and make the side effects safe to repeat.
Support two active secrets during rotation, verify against both, then remove the old one after the provider is updated. Monitor failures during the change.
Sources and further reading
- Stripe webhooks documentation (docs.stripe.com)
- PayPal webhooks (developer.paypal.com)
- NIST Secure Software Development Framework (csrc.nist.gov)
Related reading
Need an implementation review?
Send the repository or the design. I will review the boundary, the failure modes and the parts that will be expensive to change later.
How to cite this guide: Nur Hossain Repon, “Webhook handling: complete developer guide (2026)”, Nhrepon Portfolio, reviewed October 2026, https://nhrepon.com/posts/webhook-handling-complete-developer-guide-2026.





Comments
No comments yet.