Receiving webhooks
Everything your endpoint needs to do — accept the request, verify it, answer fast, and handle retries.
This guide walks through building an endpoint that receives deliveries from Use Webhooks, from the first request to running it in production. It covers what a delivery looks like, how to verify that it really came from us, how to respond, and how to stay correct when the same event arrives more than once.
This page exercises every element the docs support: headings, lists, tables, code fences, code tabs and callouts. Use it to check styling changes.
What a delivery looks like
Every delivery is an HTTP POST to your destination's URL with a JSON body and
three signing headers. The headers follow the
Standard Webhooks specification, so any of
its libraries can verify them.
Headers
| Header | Example | Meaning |
|---|---|---|
webhook-id | dlv_01JC3… | The delivery's id. Stable across retries. |
webhook-timestamp | 1763200000 | Unix seconds when this attempt was signed. |
webhook-signature | v1,K5oZfzN95Z9UVu1EsfQmfVNQ… | One or more space-separated v1,<base64> signatures. |
content-type | application/json | Always JSON. |
user-agent | use-webhooks/1.0 | Identifies the sender. |
Any custom headers you configured on the destination are sent too. They can't override the headers above.
Body
The body wraps the payload you published with its event type and the time the event was created:
{
"type": "invoice.paid",
"timestamp": "2026-11-15T09:12:44.512Z",
"data": {
"invoiceId": "inv_8812",
"amount": 4200,
"currency": "usd"
}
}data is exactly what you sent to POST /v1/publish, untouched.
Verifying signatures
Anyone who learns your endpoint's URL can send it requests. The signature is how you tell ours apart: it's an HMAC-SHA256 of the delivery, keyed with your destination's signing secret, which only you and Use Webhooks know.
Compute the signature over the exact bytes you received. Parsing the JSON and re-serializing it can reorder keys or change whitespace, and the signature will no longer match.
How the signature is built
- Take the
webhook-id, thewebhook-timestampand the raw body. - Join them with dots:
{id}.{timestamp}.{body}. - Strip the
whsec_prefix from your secret and base64-decode the rest to get the key. - HMAC-SHA256 the joined string with that key, then base64-encode the result.
- Prefix it with
v1,.
The header can hold several signatures separated by spaces. Accept the request if any of them matches yours. This is what keeps verification working during a secret rotation (see Rotating secrets).
With a library
The quickest route is the official Standard Webhooks library for your language. Pass it the raw body and the headers, and it checks the signature and the timestamp for you.
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.USE_WEBHOOKS_SECRET!);
export async function POST(request: Request) {
const body = await request.text();
const headers = Object.fromEntries(request.headers);
let event: { type: string; data: unknown };
try {
event = wh.verify(body, headers) as typeof event;
} catch {
return new Response("invalid signature", { status: 400 });
}
await queue.add(event.type, event.data);
return new Response(null, { status: 204 });
}By hand
If there's no library for your stack, the check is a few lines. Compare signatures with a constant-time function so the comparison itself doesn't leak how many characters matched.
import { createHmac, timingSafeEqual } from "node:crypto";
const TOLERANCE_SECONDS = 5 * 60;
export function verify(secret: string, headers: Headers, body: string): boolean {
const id = headers.get("webhook-id");
const timestamp = headers.get("webhook-timestamp");
const signatures = headers.get("webhook-signature");
if (!id || !timestamp || !signatures) return false;
// Reject old or future-dated attempts to block replays.
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = createHmac("sha256", key)
.update(`${id}.${timestamp}.${body}`)
.digest("base64");
return signatures.split(" ").some((entry) => {
const [version, signature] = entry.split(",");
if (version !== "v1" || !signature) return false;
const a = Buffer.from(signature);
const b = Buffer.from(expected);
return a.length === b.length && timingSafeEqual(a, b);
});
}Rejecting replays
The timestamp is part of what's signed, so an attacker can't change it without breaking the signature. Rejecting attempts older than a few minutes means a captured request can't be replayed later. Five minutes is a sensible window; keep your server's clock synced with NTP so honest requests aren't rejected.
Responding
Your response tells us whether the delivery worked.
- Any
2xxmarks the attempt as succeeded. The body is ignored. - Any other status, or no response before the timeout, marks it as failed and schedules a retry.
410 Gonemarks it as failed permanently: no more retries for this delivery. Use it when the thing the event refers to no longer exists on your side.
Put the event on your own queue and return 204 straight away. Doing the real
work inside the request makes slow days look like failures, and those turn
into retries that add even more load.
Timeouts
Each destination has its own timeout, set when you create it. An attempt that hasn't received response headers by then is cut off and counted as failed, even if your handler finishes the work afterwards. That's one more reason to acknowledge quickly and process in the background.
Retries
Failed attempts are retried on a schedule set per destination (falling back to your organization's default).
| Setting | Values | What it controls |
|---|---|---|
retryStrategy | exponential or linear | How the gap between attempts grows. |
baseIntervalSeconds | seconds | The first gap, which the strategy grows from. |
maxAttempts | 1 – 50 | Total attempts, including the first, before giving up. |
With an exponential strategy each gap is roughly double the last, which gives a struggling server room to recover. A linear strategy waits the same amount each time, which suits endpoints that fail briefly and come back quickly.
Every attempt shows up under Deliveries in the dashboard with its status code, duration and response body, and any failed delivery can be retried by hand once you've fixed the problem.
Handling duplicates
Retries mean the same delivery can reach you more than once: your server might
finish the work, then time out before the 2xx makes it back. Design your
handler so that processing a delivery twice has the same effect as processing it
once.
The webhook-id header is the key to this. It stays the same across every retry
of a delivery, so you can record the ids you've handled and skip repeats:
export async function handle(id: string, event: { type: string; data: unknown }) {
// A unique constraint on delivery_id makes the insert the lock.
const inserted = await db
.insertInto("processed_deliveries")
.values({ delivery_id: id })
.onConflict((oc) => oc.doNothing())
.executeTakeFirst();
if (inserted.numInsertedOrUpdatedRows === 0n) return; // already handled
await process(event);
}You only need to remember ids for as long as retries can arrive. Deleting rows older than a few days keeps the table from growing forever.
Ordering
Deliveries are not guaranteed to arrive in the order events were published. A
retry of an older event can land after a newer one. If order matters, compare
the body's timestamp with what you've already stored and ignore anything older.
Rotating secrets
Rotate a destination's signing secret whenever it may have leaked, or on a regular schedule. Rotation is built so you never drop a delivery:
- Rotate the secret in the dashboard or through the API. You get the new secret,
and the previous one keeps working until
previousSecretExpiresAt. - While both are valid, every delivery is signed with both secrets, so the
webhook-signatureheader carries two signatures. - Deploy the new secret to your endpoint. Because you accept any matching signature, requests verify before and after the deploy.
- Once the previous secret expires, deliveries carry only the new signature.
Rotate straight away and choose the shortest expiry for the old secret. Until it expires, whoever holds it can still sign requests your endpoint will accept.
Testing locally
Your endpoint has to be reachable from the internet to receive deliveries. While developing, expose your local server with a tunnel and point a destination at it:
# Start your app, then open a tunnel to it
npx localtunnel --port 3000Then publish a test event and watch it arrive in your terminal and in the dashboard's Deliveries page.
Production checklist
Before you go live, check each of these:
- The endpoint is served over HTTPS.
- Every request's signature is verified against the raw body.
- Attempts older than five minutes are rejected.
- The handler returns
2xxwithin the destination's timeout. - Work happens on a queue, not inside the request.
- Repeated
webhook-ids are detected and skipped. - The signing secret lives in your secret manager, not in source control.
- You know how to rotate the secret without downtime.
Troubleshooting
Every signature fails
- Make sure you're hashing the raw body. Frameworks that parse JSON for you often need a raw-body option on this one route.
- Check you're using this destination's secret. Each destination has its own.
- Make sure the
whsec_prefix is stripped before decoding the key.
Deliveries show as timed out, but my handler ran
Your handler is doing its work before responding. Return 2xx first and move
the work to a background job.
I'm receiving the same event twice
That's a retry after an attempt we couldn't confirm. Deduplicate on webhook-id
as described in Handling duplicates.
Still stuck? Open the failing delivery in the dashboard: the response body and status code your server returned are usually enough to spot the cause.