A webhook sends data to another organisation's URL. A mistyped URL or compromised receiver can expose the whole payload. An unsigned request also lets an attacker impersonate your service and trigger actions such as shipping an order.
When designing a webhook API, send a thin, signed notification containing IDs. The receiver verifies the raw request body before trusting it, then fetches details through an authenticated API. This limits disclosure and keeps access checks on the data read. Because senders retry, plan for duplicates and failed deliveries on both sides.
Northwind notifies a delivery partner that order 123 has shipped. Both requests use example data and travel over HTTPS to the same endpoint.
POST /hooks/northwind HTTP/1.1Host: partner.example.comContent-Type: application/jsonContent-Length: 211{"eventType": "order.shipped","orderId": "123","customer": { "name": "Example Customer", "email": "customer@example.com" },"total": 4180.00,"deliveryNotes": "Leave at the example reception desk"}
❌ Figure: Bad example - The unsigned notification exposes customer details and lets forged requests trigger order processing
POST /hooks/northwind HTTP/1.1Host: partner.example.comContent-Type: application/jsonContent-Length: 109webhook-id: evt_EXAMPLE_ONLY_123webhook-timestamp: 1793887205webhook-signature: v1,3OmCqmj4FEULIsBi0QE8JVmjDSMcrvolxQDr1KQ9Wos={"eventType": "order.shipped","occurredAt": "2026-11-05T14:00:00Z","subject": { "orderId": "123" }}
✅ Figure: Good example - The signed notification identifies the same order while an authorised API read controls access to customer details
The partner verifies the second request, then fetches https://api.example.com/orders/123 using its own API credential. The API checks that the partner can read this order. Use a configured API base URL and validate the ID; never send credentials to a URL supplied in the notification.
The good request uses . Its signature matches the exact UTF-8 body shown, with LF newlines and no final newline, using the UTF-8 bytes of the public test key EXAMPLE_ONLY_TEST_SIGNING_KEY_2026. Standard Webhooks libraries take that key in its base64 form, whsec_RVhBTVBMRV9PTkxZX1RFU1RfU0lHTklOR19LRVlfMjAyNg==. This is example data; the fixed attempt timestamp has expired. Real deliveries need a fresh timestamp and a securely provisioned endpoint key.
A signature protects integrity; it does not encrypt the payload. Use HTTPS and minimise identifiers and metadata too when they reveal sensitive information.
Thin notifications add an API call and depend on API availability. A later fetch returns current state, which may have changed or been deleted. If the receiver needs event-time state or cannot call the API, include only the necessary snapshot fields. See Stripe's thin and snapshot event comparison.
Use the sender's verification library and signing scheme. Never parse JSON and serialise it again to verify a signature: even a whitespace change alters the signed bytes. Reject failed verification before fetching details or performing business actions.
For Node.js, install standardwebhooks and save this helper as verify.mjs. It accepts the raw UTF-8 JSON Buffer, request headers and an endpoint secret from trusted configuration. Capture the body before any JSON parser; with Express's raw body middleware, use express.raw({ type: "application/json" }) on this route and set a request size limit.
import { Webhook } from "standardwebhooks";export function verifyDelivery(rawBody, headers, signingSecret) {if (!Buffer.isBuffer(rawBody)) {throw new TypeError("Capture the body before JSON parsing");}// Reject invalid UTF-8; pass the original bytes to the verifier.new TextDecoder("utf-8", { fatal: true }).decode(rawBody);return new Webhook(signingSecret).verify(rawBody, headers);}
This helper is tested with Node.js 24.18.0 and standardwebhooks 1.1.1. The Standard Webhooks JavaScript library checks signatures in constant time and rejects timestamps more than five minutes old or ahead. Catch verification errors at the HTTP boundary and return a failure response. Verification does not replace schema validation. Record each webhook-id and skip any you have already processed, because retries reuse the same ID and a captured request stays valid for five minutes.
Keep the real endpoint secret in secure configuration. This deliberately unusable placeholder is example data:
WEBHOOK_SIGNING_SECRET=whsec_EXAMPLE_ONLY_do_not_use
A valid signature shows the request was signed by a holder of the endpoint key, not that this is the first delivery.
webhook-id - Verify the request, then save the ID and the queued work in one transaction, with a unique constraint on the ID for that endpoint. Answer a repeated ID with a 2xx without queuing it again. Keep IDs for as long as the sender retries, not just the five-minute timestamp window2xx once that transaction commits, then fetch details and process in the background. Mark the event complete in the same transaction as its database changes, and make external effects idempotent, so a crash leaves it queued instead of lost. Slow work inside the handler causes timeouts, and a timeout causes another deliveryorder.shipped can arrive after order.delivered. Fetching current state through the API avoids applying a stale payload, but two workers can still commit out of order. Process one order at a time, or check its version before writingThe sender has duties too. A notification sent once and forgotten is lost whenever the receiver is briefly down.
2xx, including a timeout, as a failed attempt. Retry with bounded exponential backoff and jitter, but stop on 410 Gone and respect Retry-After. Keep the same webhook-id and sign each attempt with a fresh timestamp. Let receivers list failed deliveries and replay themwebhook-signature header carries both versioned signatures, separated by a space, so receivers switch without downtimeSee the Standard Webhooks specification for signing, retries and delivery guidance.
Confirm each of these on a test endpoint:
webhook-id delivered twice produces one business action and two 2xx responses500, then recovers, gets the event again with the same ID