Verify webhook signatures

Check that each delivery came from your account using the webhook-id, webhook-timestamp and webhook-signature headers and the endpoint's whsec_ secret.

Every webhook delivery is signed according to the Standard Webhooks specification. Before you act on an event, recompute the signature with the endpoint's secret and compare it with the one in the request. You can copy the code on this page or use any Standard Webhooks library, which takes the whsec_ secret exactly as you received it.

The signing secret#

The secret appears once, in the secret field of the response to POST $BUSINESS_API/developer/webhooks (create an endpoint) and POST $BUSINESS_API/developer/webhooks/{id}/roll (roll the secret). Later reads of the endpoint leave it out, so put it in your secret store straight away.

Its format is whsec_ followed by 32 random bytes in base64. Those 32 bytes are the HMAC key: strip the prefix and base64-decode the remainder before signing.

The three headers#

Header Contents
webhook-id The delivery ID (dlv_). It stays the same across every attempt of one delivery, so it is the key for dropping duplicates.
webhook-timestamp Unix seconds at the start of the attempt. A retry carries a fresh value and therefore a fresh signature.
webhook-signature One or more space-separated v1,<base64> signatures.

The signature is the base64-encoded HMAC-SHA256 of webhook-id + . + webhook-timestamp + . + body. Sign the raw bytes you received: a framework that parses the JSON and serialises it again will produce a different string and the comparison fails.

A sample delivery#

Here is a genuine webhook.test request signed with the secret whsec_bxwqm+TQP3pRyOK5bUCn8xhc6bIEfabzwehbKdB/Sm4=. Use it as a fixture in your tests:

http
POST /hooks/billing HTTP/1.1
Content-Type: application/json
User-Agent: Gota-Webhooks/1.0
webhook-id: dlv_2pR8kF6wNz1QcT4bVx7LmHs9JdR
webhook-timestamp: 1795079647
webhook-signature: v1,wWR3EcUtcs9smHNXisdbsUP5PNZ7xWNciZy+vbXESW4=

{"api_version":"v1","created_at":"2026-11-19T09:14:07.512Z","data":{"attributes":{"message":"This is a test event."},"resource":{"id":"whk_2pR7tLx4NcQ9bV3mKw8ZsYe1HdF","sequence":1,"type":"webhook"},"resource_id":"whk_2pR7tLx4NcQ9bV3mKw8ZsYe1HdF","resource_type":"webhook"},"id":"wev_2pR8kD3vXq6NtB9wLc5YmJs2HaE","tenant_id":"ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF","type":"webhook.test"}

Its timestamp is in the past, so turn off the time-window check while you run this request through a unit test.

Verify in code#

All three versions behave alike: they refuse requests missing a header, refuse timestamps more than 300 seconds from the server clock (the five-minute replay window the specification recommends) and compare signatures in constant time.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody, headers, secret) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  const sigHeader = headers["webhook-signature"];
  if ([id, ts, sigHeader].some((v) => v === undefined || v === "")) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key)
    .update(Buffer.concat([Buffer.from(`${id}.${ts}.`), rawBody]))
    .digest();
  return sigHeader.trim().split(/\s+/).some((entry) => {
    const [version, b64] = entry.split(",", 2);
    if (version === "v1" && b64) {
      const candidate = Buffer.from(b64, "base64");
      return candidate.length === expected.length && timingSafeEqual(candidate, expected);
    }
    return false;
  });
}

Answering a bad signature#

Reply with a 4xx status and leave the event unprocessed. On the sending side, a plain 4xx is retried only a few times before the delivery moves to paused and waits for you to fix the endpoint; a 410 pauses it on the first answer. Once your check is fixed, send the paused deliveries again with Resend failed on the webhook's page or with POST $BUSINESS_API/developer/webhooks/{id}/redeliveries, which by default picks up the failed and paused deliveries from the last 24 hours and accepts a window of up to 7 days.

Rolling the secret without dropping deliveries#

Rolling needs the developer:write scope. The optional overlap_seconds field sets how long the old secret keeps signing, from 0 to 604800 seconds, defaulting to 86400; 0 retires the old secret at once.

bash
curl -X POST $BUSINESS_API/developer/webhooks/whk_2pR7tLx4NcQ9bV3mKw8ZsYe1HdF/roll \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"overlap_seconds": 3600}'
json
{
  "id": "whk_2pR7tLx4NcQ9bV3mKw8ZsYe1HdF",
  "url": "https://erp.example.test/hooks/billing",
  "description": "Invoice sync",
  "events": ["invoice.paid", "payment.received"],
  "enabled": true,
  "created_at": "2026-10-02T13:40:11Z",
  "updated_at": "2026-11-19T10:02:55Z",
  "previous_secret_expires_at": "2026-11-19T11:02:55Z",
  "health": "healthy",
  "secret": "whsec_Qm3v9Lx2cT8pZr5NbW1yKd7HsF4jGa6eUo0iXqCtVhE="
}

Until previous_secret_expires_at passes, webhook-signature carries two v1 signatures, one per secret. Deploy the new secret to your receiver inside that window: the code above accepts the request when either signature matches.

Test it#

  • POST $BUSINESS_API/developer/webhooks/{id}/test queues a webhook.test event for that endpoint alone, through the normal queue with signing and retries. It answers 202 with the new delivery, or 409 when the endpoint is disabled or paused.
  • gotactl webhooks listen --forward-to http://localhost:3000/webhooks forwards sandbox events to your machine, signed with a whsec_ secret generated for the session and printed at start-up. In this mode webhook-id holds the event ID (wev_). Pass --events with a comma-separated list of types to forward only those.
  • gotactl events trigger invoice.paid fires a real event in the sandbox so you can follow the check from sender to receiver.

Next steps#