ブログ · · 約 6 分で
Standard Webhooks の署名の確かめ方:webhook-id・timestamp・signature
Standard Webhooks の
要点
- Standard Webhooks の
署名は、 webhook-id・webhook-timestamp・本文を 「.」 で つないだ文字列を HMAC-SHA256 に かけ、 base64 に した 値です。 - 鍵は
whsec_ を 外した 残りを base64 で 戻した バイト列で、 本文は 届いたままの バイト列を 使います。 JSON を 読み直した 文字列では 合いません。 - 時刻が
前後 5 分の 中かを 確かめ、 空白区切りの 署名の どれか 1 つが 合えば 通します。 webhook-id は 重複の 見分けに 使います。
Standard Webhooks のwebhook-id・webhook-timestamp・本文を. でwebhook-signature のwhsec_ の
3 つの見出し
署名に
| 見出し | 中身 | 使い道 |
|---|---|---|
webhook-id |
送る |
署名の |
webhook-timestamp |
送った |
署名の |
webhook-signature |
v1,<base64>。 |
計算した |
ID と
署名する文字列と鍵
署名するのはID.時刻.本文 の
msg_2KWPBgLlAfxdpx2AI54pPJ85f4W.1733376000.{"type":"tool.call","tool":"find_slots",...}鍵はwhsec_ でwhsec_ を
受ける側の手順
公式の
- 3 つの
見出しを 読む。 無ければ 400 などで 断る。 webhook-timestampが今の 時刻から 前後 5 分の 中かを 確かめる (公式の ライブラリの 幅) 。 - 鍵の
whsec_を外し、 base64 で 戻して バイト列に する。 ID.時刻.本文をHMAC-SHA256 に かけ、 base64 に する。 本文は 届いたままの バイト列を 使う。 webhook-signatureを空白で 分け、 v1,で始まる 値の どれかが 4 と 一致するかを 定数時間の 比較で 確かめる。 - 通ったら
webhook-idを記録し、 同じ ID が また 届いたら 処理せずに 2xx を 返す。
Node.js のコード
ライブラリstandardwebhooks)express.raw を
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 は確かめ終わった JSON
res.json({ ok: true, tool: body.tool });
});
app.listen(3000);ライブラリを
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 のコード
Python のpip install standardwebhooks)whsec_ のWebhookVerificationError が
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"])署名が合わないときの原因
| 症状 | よく |
直し方 |
|---|---|---|
| いつも |
本文を |
読む前のexpress.raw) |
| いつも |
whsec_… の |
whsec_ を |
| ときどき合わない | サーバーの |
NTP で |
| 鍵を |
最初の |
空白区切りの |
| 本番だけ合わない | テストの |
環境ごとの |
鍵の切り替え
鍵をwebhook-signature に
voicast での署名の確かめ
voicast は、
- 会話中の
ツール : AI がツールを 使うと 決めると、 voicast が ツールの urlにPOST します (本文は { type: 'tool.call', tool, arguments, call })。 鍵 ( whsec_…)は 環境ごとに 1 つで、 管理画面か MCP の get_tools_secretで確かめます。 作り直してから 24 時間は、 古い鍵の 署名も 並べて 送ります。 - 会話の
あとの :Webhook call.ended・call.summary_readyなどは、voicast が Standard Webhooks の 署名を 付けて 送ります。 送り先は POST /v1/webhooks/portalで作るリンクの 画面で 登録します。
ツールの
よくある質問
時刻の幅は 5 分より広げてもいいですか。
広げる
webhook-id は何に使えばいいですか。
重複の
署名を確かめたら、送り元の IP は確かめなくていいですか。
署名が