ブログ · · 約 6 分で読めます

Standard Webhooks の署名の確かめ方:webhook-id・timestamp・signature

Standard Webhooks の署名を受ける側で確かめる手順を、3 つの見出し、署名する文字列、whsec_ の鍵の戻し方、時刻の幅、鍵の切り替えまで解説します。Node.js と Python の動くコードと、合わないときの原因の表も載せます。

要点

  • Standard Webhooks の署名は、webhook-id・webhook-timestamp・本文を「.」でつないだ文字列を HMAC-SHA256 にかけ、base64 にした値です。
  • 鍵は whsec_ を外した残りを base64 で戻したバイト列で、本文は届いたままのバイト列を使います。JSON を読み直した文字列では合いません。
  • 時刻が前後 5 分の中かを確かめ、空白区切りの署名のどれか 1 つが合えば通します。webhook-id は重複の見分けに使います。

Standard Webhooks の署名は、webhook-id・webhook-timestamp・本文を . でつないだ文字列を、鍵で HMAC-SHA256 にかけて base64 にした値です。受ける側は同じ計算をして webhook-signature の値と比べ、あわせて時刻が古すぎないかを確かめます。公式のライブラリを使えば数行で済みますが、本文を届いたまま渡すことと、鍵の whsec_ の扱いでつまずきやすいので、仕組みから順に説明します。仕様は Standard Webhooks の仕様の本文にあります。

3 つの見出し

署名に使うのは、要求に付く 3 つの見出しです。どれか 1 つでも無ければ、その要求は断ります。

見出し 中身 使い道
webhook-id 送るものごとの一意の ID 署名の材料・重複の見分け
webhook-timestamp 送った時刻(Unix 時刻の秒) 署名の材料・古い要求の拒否
webhook-signature v1,<base64>。空白区切りで複数並ぶことがある 計算した値と比べる

ID と時刻を署名に含めるのは、途中で書き換えられないようにするためです。ID を変えて「別の知らせ」に見せかけることも、時刻を変えて古い要求を送り直すこともできなくなります。

署名する文字列と鍵

署名するのは ID.時刻.本文 の文字列です。

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

鍵は whsec_ で始まる文字列で渡されますが、そのまま HMAC の鍵にはしません。whsec_ を外し、残りを base64 で戻したバイト列を鍵にします。ここを間違えると、計算はできても値が合いません。

受ける側の手順

公式のライブラリが行っている確かめ方は、次の 6 つです。自分で書くときもこの順にします。

  1. 3 つの見出しを読む。無ければ 400 などで断る。
  2. webhook-timestamp が今の時刻から前後 5 分の中かを確かめる(公式のライブラリの幅)。
  3. 鍵の whsec_ を外し、base64 で戻してバイト列にする。
  4. ID.時刻.本文 を HMAC-SHA256 にかけ、base64 にする。本文は届いたままのバイト列を使う。
  5. webhook-signature を空白で分け、v1, で始まる値のどれかが 4 と一致するかを定数時間の比較で確かめる。
  6. 通ったら webhook-id を記録し、同じ ID がまた届いたら処理せずに 2xx を返す。

Node.js のコード

ライブラリ(npm の standardwebhooks)を使う形です。Express では、JSON として読む前の本文が要るので express.raw を使います。

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 は確かめ終わった JSON
  res.json({ ok: true, tool: body.tool });
});

app.listen(3000);

ライブラリを使わずに書くと、次のようになります。

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 のコード

Python のライブラリ(pip install standardwebhooks)も、whsec_ の付いた鍵をそのまま受け取り、見出しの名前を小文字にそろえてから確かめます。失敗すると 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"])

署名が合わないときの原因

症状 よくある原因 直し方
いつも合わない 本文を JSON として読んでから文字列に戻している 読む前の生の本文を渡す(Express は express.raw)
いつも合わない whsec_… の文字列のまま鍵にしている whsec_ を外して base64 で戻す(ライブラリは自動)
ときどき合わない サーバーの時計がずれている NTP で時計を合わせる
鍵を作り直した直後だけ合わない 最初の署名だけを比べている 空白区切りの署名をすべて比べる
本番だけ合わない テストの環境の鍵を使っている 環境ごとの鍵を確かめる

鍵の切り替え

鍵を作り直すときは、送る側がしばらく新旧 2 つの鍵で署名し、webhook-signature に空白区切りで並べます。受ける側は、どれか 1 つが合えば通すので、鍵を入れ替えるまでのあいだも止まりません。受ける側の作りとしては「署名を全部比べる」ことだけを守れば十分です。

voicast での署名の確かめ

voicast は、2 か所で Standard Webhooks の署名を付けます。

  • 会話中のツール: 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 で作るリンクの画面で登録します。

ツールの応答は 8 秒まで待つので、署名の確かめはライブラリに任せ、重い処理を前に置かないようにします。ツールの作り方は会話中のツールの記事、会話のあとの知らせは会話のあとの Webhook の記事で扱います。

よくある質問

時刻の幅は 5 分より広げてもいいですか。

広げるほど、盗まれた要求を送り直されたときに通ってしまう時間が長くなります。時計のずれが原因なら、幅を広げるより NTP で時計を合わせるほうが安全です。

webhook-id は何に使えばいいですか。

重複の見分けに使います。送る側は送り直しでも同じ ID を使うので、処理した ID を記録しておき、同じ ID が届いたら処理せずに 2xx を返します。

署名を確かめたら、送り元の IP は確かめなくていいですか。

署名が合えば、鍵を持つ相手が送った本文だと分かります。IP の制限は追加の守りにはなりますが、送り元の IP が変わることもあるので、署名の確かめを先に必ず行います。

関連記事