# 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:

```javascript
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:

```http
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.

```bash
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}'
```

```json
{
  "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](/docs/webhooks/verify) for the Python and Go versions, and [the webhook overview](/docs/webhooks/overview) for retries and delivery statuses.

