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

```javascript
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;
  });
}
```

```python
import base64, hashlib, hmac, time

def verify_webhook(raw_body: bytes, headers: dict, secret: str) -> bool:
    wid = headers.get("webhook-id")
    ts = headers.get("webhook-timestamp")
    sig_header = headers.get("webhook-signature")
    if not (wid and ts and sig_header):
        return False
    if abs(time.time() - int(ts)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    digest = hmac.new(key, f"{wid}.{ts}.".encode() + raw_body, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(digest).decode()
    return any(hmac.compare_digest(part, expected) for part in sig_header.split())
```

```go
func verifyWebhook(rawBody []byte, h http.Header, secret string) bool {
	id, ts, sigs := h.Get("webhook-id"), h.Get("webhook-timestamp"), h.Get("webhook-signature")
	sec, tsErr := strconv.ParseInt(ts, 10, 64)
	key, keyErr := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
	fresh := tsErr == nil && math.Abs(time.Since(time.Unix(sec, 0)).Seconds()) <= 300
	if fresh && keyErr == nil && len(id) > 0 && len(sigs) > 0 {
		mac := hmac.New(sha256.New, key)
		mac.Write([]byte(id + "." + ts + "."))
		mac.Write(rawBody)
		expected := "v1," + base64.StdEncoding.EncodeToString(mac.Sum(nil))
		for _, part := range strings.Fields(sigs) {
			if hmac.Equal([]byte(part), []byte(expected)) {
				return true
			}
		}
	}
	return false
}
```

✓ Checkpoint: with the sample request, the secret above and the time window off, the function returns true; change one character of the body or of `webhook-id` and it returns 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

- [Retries and redelivery](/docs/webhooks/retries): the retry schedule and when a delivery fails for good.
- [Testing webhooks](/docs/webhooks/testing): the test send and the deliveries log.
- [Best practices](/docs/webhooks/best-practices): answering quickly and deduplicating on `webhook-id`.
- [Listen to events with webhooks](/docs/guides/listen-webhooks): setting up an endpoint from start to finish.

