# Verifying Standard Webhooks Signatures

> How to verify Standard Webhooks signatures: the three headers, the signed string, the whsec_ key, timestamp checks and rotation, with Node.js and Python code.

Published: 2026-11-05
Source: https://voicast.jp/en/blog/standard-webhooks-signature-verification

## Key points

- A Standard Webhooks signature is base64(HMAC-SHA256(key, "webhook-id.webhook-timestamp.body")), sent as v1,<base64> in the webhook-signature header.
- The key is the base64 part after whsec_, decoded to bytes, and the body must be the exact raw bytes you received - not re-serialized JSON.
- Reject timestamps more than 5 minutes off, accept if any of the space-separated signatures matches, and use webhook-id to drop duplicates.

A Standard Webhooks signature is an HMAC-SHA256 over `webhook-id`, `webhook-timestamp` and the raw body joined with dots, base64-encoded. To verify it, recompute that value with your secret, compare it to the `webhook-signature` header, and check the timestamp is recent. The official libraries do it in a couple of lines; most bugs come from passing parsed JSON instead of the raw body, or using the `whsec_` secret as-is. Here's how it works and how to get it right. The full spec lives in the [Standard Webhooks repository](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md).

## The three headers

Every signed request carries three headers. If any is missing, reject the request.

| Header | Contains | Used for |
|---|---|---|
| `webhook-id` | A unique ID per message | Signature input, deduplication |
| `webhook-timestamp` | Send time, Unix seconds | Signature input, rejecting stale requests |
| `webhook-signature` | `v1,<base64>`, possibly several separated by spaces | Comparing with your computed value |

The ID and timestamp are part of the signed content so nobody can tamper with them. An attacker can't relabel a message as a new one, or replay an old request with a fresh timestamp, without breaking the signature.

## What gets signed, and with which key

The signed content is `id.timestamp.body`:

```text
msg_2KWPBgLlAfxdpx2AI54pPJ85f4W.1733376000.{"type":"tool.call","tool":"find_slots",...}
```

Secrets are handed out as strings starting with `whsec_`. Don't use that string directly as the HMAC key. Strip the `whsec_` prefix and base64-decode the rest; those bytes are the key. Get this wrong and your code runs fine, but no signature ever matches.

## Verification, step by step

This is what the official libraries do. If you write your own, follow the same order:

1. Read the three headers. Reject with 400 if any is missing.
2. Check that `webhook-timestamp` is within 5 minutes of now (the window the official libraries use).
3. Strip `whsec_` from the secret and base64-decode it.
4. Compute HMAC-SHA256 over `id.timestamp.body` using the raw body bytes, then base64-encode.
5. Split `webhook-signature` on spaces. Accept if any `v1,` entry matches step 4, compared in constant time.
6. Record the `webhook-id`. If the same ID shows up again, return 2xx without processing it twice.

## Node.js

With the `standardwebhooks` npm package. In Express, use `express.raw` so you get the body before anything parses it.

```ts
import express from 'express';
import { Webhook } from 'standardwebhooks';

const app = express();
const wh = new Webhook(process.env.VOICAST_TOOLS_SECRET!); // whsec_...

app.post('/voicast/tools', express.raw({ type: 'application/json' }), (req, res) => {
  let body: any;
  try {
    body = wh.verify(req.body, req.headers as Record<string, string>);
  } catch {
    return res.status(401).json({ error: 'invalid signature' });
  }
  // body is the verified, parsed JSON
  res.json({ ok: true, tool: body.tool });
});

app.listen(3000);
```

Without the library, using only `node:crypto`:

```ts
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret: string, raw: Buffer, h: Record<string, string | undefined>): boolean {
  const id = h['webhook-id'];
  const ts = h['webhook-timestamp'];
  const sigs = (h['webhook-signature'] ?? '').split(' ');
  if (!id || !ts || !/^\d+$/.test(ts)) 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(`${id}.${ts}.`).update(raw).digest();
  return sigs.some((s) => {
    const [ver, b64] = s.split(',');
    if (ver !== 'v1' || !b64) return false;
    const got = Buffer.from(b64, 'base64');
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}
```

## Python

The Python package (`pip install standardwebhooks`) accepts the `whsec_` secret directly and lowercases header names before checking. Failures raise `WebhookVerificationError`.

```python
import os
from flask import Flask, request, jsonify
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

app = Flask(__name__)
wh = Webhook(os.environ["VOICAST_TOOLS_SECRET"])  # whsec_...

@app.post("/voicast/tools")
def tools():
    try:
        body = wh.verify(request.get_data(), dict(request.headers))
    except WebhookVerificationError:
        return jsonify(error="invalid signature"), 401
    return jsonify(ok=True, tool=body["tool"])
```

## When signatures don't match

| Symptom | Likely cause | Fix |
|---|---|---|
| Never matches | Body was parsed as JSON and re-serialized | Pass the raw body (`express.raw`, `request.get_data()`) |
| Never matches | `whsec_...` string used directly as the key | Strip the prefix and base64-decode (libraries do this for you) |
| Fails intermittently | Server clock drift | Sync the clock with NTP |
| Fails only right after a key rotation | Only the first signature is checked | Check every space-separated signature |
| Fails only in production | Using the test environment's secret | Confirm which environment the secret belongs to |

Body-parsing middleware is the usual suspect. Frameworks like Express, Next.js API routes and FastAPI all make it easy to read JSON and hard to keep the original bytes; whitespace or key order changes are enough to break the HMAC.

## Rotating keys without downtime

During a rotation, the sender signs each message with both the old and new keys and puts both signatures in `webhook-signature`. Because your receiver accepts any matching signature, it keeps working whether it holds the old key or the new one. The only rule on your side: check all signatures, not just the first.

## Doing this with voicast

voicast signs with Standard Webhooks in two places:

- **In-call tools.** When the AI decides to use a tool, voicast POSTs `{ type: 'tool.call', tool, arguments, call }` to the tool's `url`. There's one signing secret (`whsec_...`) per environment, which you can see in the dashboard or with the MCP tool `get_tools_secret`. After you rotate it, voicast also includes a signature with the old key for 24 hours.
- **Post-call webhooks.** Events such as `call.ended` and `call.summary_ready` are sent by voicast with Standard Webhooks signatures. You register the endpoint on the portal page linked from `POST /v1/webhooks/portal`.

voicast waits up to 8 seconds for a tool to respond, so let the library handle verification and keep anything slow out of the request path. See [function calling in live calls](https://voicast.jp/en/blog/voice-ai-function-calling) for tool design and [post-call webhooks](https://voicast.jp/en/blog/post-call-webhooks) for the events.

## FAQ

### Can I widen the timestamp window beyond 5 minutes?

You can, but every extra minute is more time for a captured request to be replayed successfully. If clock drift is the real problem, fix the clock with NTP rather than loosening the check.

### What should I do with webhook-id?

Use it for deduplication. Senders reuse the same ID when they retry, so store the IDs you've processed and return 2xx without doing the work again when a known ID arrives.

### If the signature checks out, do I still need an IP allowlist?

A valid signature already proves the message came from someone holding the secret. An allowlist can be an extra layer, but sender IPs can change, so never use it instead of signature verification.
