Move your receiver to Standard Webhooks signatures
Every webhook delivery is now signed with the webhook-id, webhook-timestamp and webhook-signature headers and a whsec_ secret. What changes in your receiver, how to verify, and how to roll the secret without losing events.
What changed#
Webhook deliveries no longer carry the vendor-prefixed X- signature and event-ID headers. Each POST to your endpoint now follows the Standard Webhooks specification and sends three headers:
| Header | Value |
|---|---|
webhook-id |
The delivery ID, a dlv_ identifier. It stays the same when the delivery is retried automatically or with a manual retry, so use it to drop duplicates. |
webhook-timestamp |
Unix time in seconds when this attempt started. A retry gets a new timestamp and a new signature. |
webhook-signature |
One or more v1,<base64> tokens separated by a space. |
The signature is an HMAC-SHA256 over the string webhook-id.webhook-timestamp.body, where body is the raw request body exactly as received. The key is the signing secret with its whsec_ prefix removed and the remainder base64-decoded. Secrets are 32 random bytes, so you get them as whsec_ followed by 44 base64 characters.
Before and after#
Your old handler read a single signature header. The new one needs all three values and the raw body:
import crypto from "node:crypto";
export function verify(headers, rawBody, secret) {
const id = headers["webhook-id"];
const ts = headers["webhook-timestamp"];
const sig = headers["webhook-signature"];
if ([id, ts, sig].some((value) => value === undefined)) return false;
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = crypto.createHmac("sha256", key)
.update(`${id}.${ts}.`).update(rawBody).digest();
return sig.trim().split(/\s+/).some((token) => {
const [version, b64] = token.split(",", 2);
const candidate = Buffer.from(b64 || "", "base64");
return version === "v1" && candidate.length === expected.length
&& crypto.timingSafeEqual(candidate, expected);
});
}
Accept the request when any token matches. The 300-second window is the one used by the receiver examples in Node.js, Python and Go; pick your own if your clocks drift, but keep a limit so an old captured request cannot be replayed.
A delivery looks like this on the wire:
POST /hook HTTP/1.1
Content-Type: application/json
webhook-id: dlv_2Kxa1bR8mTqN5vWz3HcJ7pLsE0d
webhook-timestamp: 1795075200
webhook-signature: v1,K5oZfzN95Z9Zl5Zl1ZgL4jYy8V9ZtqzF3JtM5YhJ1Wk=
The body carries the event: id (a wev_ identifier), type, api_version, tenant_id, created_at and data.
Roll the secret during the move#
If you are unsure which secret your receiver holds, issue a new one. rollDeveloperWebhookSecret needs the developer:write scope. overlap_seconds sets how long the old secret keeps signing next to the new one, from 0 to 604800, and defaults to 86400.
curl -sS -X POST "$BUSINESS_API/developer/webhooks/whk_2Kx9fQmZ7pLwR4tYb8NcV1sD3eH/roll" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"overlap_seconds": 86400}'
{
"id": "whk_2Kx9fQmZ7pLwR4tYb8NcV1sD3eH",
"url": "https://erp.example.test/hook",
"description": "Invoice sync",
"events": ["invoice.issued", "invoice.paid"],
"enabled": true,
"health": "healthy",
"created_at": "2026-10-02T08:14:00Z",
"updated_at": "2026-11-19T09:30:00Z",
"previous_secret_expires_at": "2026-11-20T09:30:00Z",
"secret": "whsec_Q2v8nR4kT1mZ7xY0pL3sW6bH9dF2gJ5cN8aE1uK4iO0="
}
The response is 201. Apart from the create call, this is the only response that includes secret, so store it straight away. Until previous_secret_expires_at, webhook-signature holds two tokens, one per secret, which is why your check must try every token. Sending 0 retires the old secret at once, and deliveries carry a single token again. A value outside the range answers 400; an unknown endpoint answers 404.
Verify your integration#
Run gotactl webhooks listen --forward-to http://localhost:3000/hook. The CLI prints a fresh whsec_ secret for the session and signs each forwarded event with the same three headers; it sends the event ID as webhook-id. With a sandbox as the active context, run gotactl events trigger invoice.paid in a second terminal and confirm your handler answers 200. To test the real delivery path to a deployed endpoint, call POST $BUSINESS_API/developer/webhooks/{id}/test, which queues a sample event and answers 202 with the delivery in status pending. A disabled or paused endpoint answers 409, so enable or resume it first.
Read how to verify signatures for the Python and Go versions, and the webhook overview for retries and delivery statuses.