Guide & TutorialsBuild a resilient webhook consumer
Guide & Tutorials
Build a resilient webhook consumer
Verify, acknowledge, and process Northstar events without losing work.
Webhook endpoints sit on the boundary between two systems. They must reject forged requests, respond quickly during traffic spikes, and safely handle repeated delivery.
Photo by Headway on Unsplash.
Receive the raw request
Signature verification must use the exact bytes sent by Northstar. Parsing and re-encoding JSON before verification can change whitespace or escaping and invalidate an otherwise correct signature.
ts
const rawBody = await request.text();
const signature = request.headers.get('northstar-signature');
verifyNorthstarSignature(rawBody, signature, process.env.WEBHOOK_SECRET);Return
401 Unauthorized when verification fails. Do not reveal which part of the signature was incorrect.Acknowledge before processing
After verification, persist the event in a durable queue and return a successful response. Sending email, rebuilding a search index, or calling another API inside the webhook request increases latency and creates unnecessary delivery retries.
ts
await queue.send({
eventId: event.id,
type: event.type,
payload: event.data,
});
return new Response(null, { status: 204 });Make processing idempotent
Northstar uses at-least-once delivery, so the same event may arrive more than once. Store the event identifier with the completed operation. When a duplicate arrives, acknowledge it without repeating the side effect.
Note
Delivery order is not guaranteed. Retrieve the current resource before making a decision that depends on its latest state.
Test failure paths
Exercise invalid signatures, expired timestamps, duplicate events, unavailable queues, and worker retries before launch. A webhook integration is production-ready only when these failure paths are predictable.