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:
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;
});
}
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())
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
}
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.
curl -X POST $BUSINESS_API/developer/webhooks/whk_2pR7tLx4NcQ9bV3mKw8ZsYe1HdF/roll \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"overlap_seconds": 3600}'
{
"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}/testqueues awebhook.testevent for that endpoint alone, through the normal queue with signing and retries. It answers202with the new delivery, or409when the endpoint is disabled or paused.gotactl webhooks listen --forward-to http://localhost:3000/webhooksforwards sandbox events to your machine, signed with awhsec_secret generated for the session and printed at start-up. In this modewebhook-idholds the event ID (wev_). Pass--eventswith a comma-separated list of types to forward only those.gotactl events trigger invoice.paidfires a real event in the sandbox so you can follow the check from sender to receiver.
Next steps#
- Retries and redelivery: the retry schedule and when a delivery fails for good.
- Testing webhooks: the test send and the deliveries log.
- Best practices: answering quickly and deduplicating on
webhook-id. - Listen to events with webhooks: setting up an endpoint from start to finish.