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

Webhook の重複と冪等性:webhook-id・一意制約・処理済みの記録

Webhook が重複して届く理由と、受ける側の 3 つの守り方(一意制約・処理済みの記録・upsert)、同時に届いたときの扱いを、Stripe・GitHub・Shopify・Slack・LINE の ID の表とコードで示します。

要点

  • 送る側は「少なくとも 1 回」届ける設計なので、同じイベントが 2 回以上届くことは避けられません。
  • 受ける側は、イベントの ID を一意制約つきで記録し、入らなければ 2 回目として処理を飛ばして 2xx を返します。
  • ID の場所は送る側ごとに違います(webhook-id、Stripe の event.id、GitHub の X-GitHub-Delivery、Shopify の X-Shopify-Webhook-Id など)。

Webhook を送る側の多くは、届いたことを確かめられなかったイベントを送り直します。受ける側が処理を終えていても、応答が送る側に届かなければ失敗として再送されるので、同じイベントが 2 回以上届くことは避けられません。受ける側は、イベントごとの ID を一意制約つきで記録し、2 回目以降は処理を飛ばして 2xx を返します。この記事では、重複が起きる理由、3 つの守り方、同時に届いたときの扱い、各社の ID の場所をまとめます。

冪等性とは

冪等性(idempotency)は、同じ操作を何度実行しても、1 回実行したときと結果が変わらない性質です。Webhook の受ける側では、同じイベントが 2 回以上届いても、処理の結果が 1 回分になることを指します。

「請求書を支払い済みにする」は何度実行しても結果が同じなので、もともと冪等です。「ポイントを 100 加算する」「メールを送る」は届くたびに結果が増えるので、そのままでは冪等になりません。こうした処理は、イベントの ID で 2 回目以降を見分けて処理を飛ばすことで、受ける側の全体を冪等にします。具体的な作り方は後述の「3 つの守り方」で示します。

重複が起きる理由

  1. 受け取ったが、2xx が送る側に届かなかった。処理を終えて応答を返す途中で接続が切れると、送る側からは失敗に見えます。
  2. タイムアウトの後に処理が終わった。送る側はタイムアウトで失敗と記録しますが、受ける側では処理が最後まで進んでいます。
  3. 送る側の障害や手動の再送。送る側のキューが同じ仕事を 2 回実行する、運用者が記録から送り直す、といった場合です。

Shopify も「ネットワークのタイムアウトや再送の後などに、同じ Webhook を複数回受け取ることがある」と書いています(Shopify、2026-09-27 に確認)。送る側の約束は「少なくとも 1 回」で、重複を除くのは受ける側の仕事です。

各社の「同じイベント」を見分ける ID

2026-09-27 に各社の公式のドキュメントで確かめた内容です。

送る側 ID の場所 再送で同じ値か 補足
Standard Webhooks webhook-id ヘッダー 同じ 仕様が冪等性のキーとして使うよう勧めている
Stripe 本文の id(evt_…) 同じ 別々に生成された 2 つの Event が同じ変更を表すことがあり、その場合は data.object の ID と type で見分ける
GitHub X-GitHub-Delivery ヘッダー 再配信でも同じ 配信ごとの GUID
Shopify X-Shopify-Webhook-Id ヘッダー ― 配信ごとの一意のキー。重複の除去にはこれを使う。X-Shopify-Event-Id は同じ操作から出た複数の配信に共通
Slack 本文の event_id 記載なし すべてのワークスペースで一意。再送には x-slack-retry-num ヘッダーが付く
LINE 本文の webhookEventId ― 再送のときは deliveryContext.isRedelivery が true

出典: Standard Webhooks の仕様、Stripe、GitHub のヘッダー、GitHub の推奨、Shopify の重複、Shopify のヘッダー、Slack、LINE

Shopify の 2 つの ID は用途が違います。同じ配信の重複を捨てるなら X-Shopify-Webhook-Id、1 つの操作から出た別々のトピックの配信をまとめて扱うなら X-Shopify-Event-Id です。

3 つの守り方

1. 一意制約による除外

いちばん単純な形です。署名を検証した後、ID を一意制約つきの表に入れ、入らなければ重複として 2xx を返します。

app.post('/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
  const event = await verifyOr400(req, res); // 署名の検証。失敗なら 400 を返して終わる
  if (!event) return;

  const id = req.header('webhook-id')!;
  const r = await db.query(
    'INSERT INTO processed_webhooks (id, received_at) VALUES ($1, now()) ON CONFLICT (id) DO NOTHING',
    [id],
  );
  if (r.rowCount === 0) return res.sendStatus(200); // 2 回目以降。処理せずに成功を返す

  await queue.add('webhook', { id, event });
  res.sendStatus(200);
});

この形の弱点は、ID を記録した後、キューに入れる前に落ちると、そのイベントは「処理済み」と記録されたまま処理されないことです。キューへの投入が確実でない場合は、次の 2 の形にします。

2. 同じトランザクションでの記録と業務の更新

業務のデータの更新と ID の記録を同じトランザクションで行うと、「記録したが処理していない」と「処理したが記録していない」のどちらも起きません。

await db.transaction(async (tx) => {
  const r = await tx.query(
    'INSERT INTO processed_webhooks (id, received_at) VALUES ($1, now()) ON CONFLICT (id) DO NOTHING',
    [id],
  );
  if (r.rowCount === 0) return; // 重複
  await tx.query('UPDATE invoices SET status = $1, paid_at = $2 WHERE id = $3', [
    'paid',
    event.data.paid_at,
    event.data.invoice_id,
  ]);
}); // 途中で失敗すれば両方とも取り消され、次の再送でやり直せる

処理の途中で外部の API を呼ぶ場合は、その API にも冪等性のキー(イベントの ID から作った値)を渡して、やり直しで 2 回実行されないようにします。

3. 何度実行しても同じ結果になる処理

「請求書を支払い済みにする」「ユーザーの状態を最新の値で上書きする」のように、何度実行しても結果が変わらない処理なら、重複を検出しなくても害はありません。INSERT … ON CONFLICT DO UPDATE(upsert)で書ける処理はこの形にできます。

逆に「ポイントを 100 加算する」「メールを送る」のように、実行するたびに結果が増える処理は、1 か 2 の形で重複を弾く必要があります。

同時に 2 通届いたとき

再送の間隔が短いと、1 通目の処理中に 2 通目が届くことがあります。「ID があるか確かめる → 無ければ処理して記録する」の順で書くと、2 通とも「まだ無い」と判断して両方を処理します。

先に一意制約つきで書き込み、書き込めた方だけが処理する形なら、データベースが 1 通だけを通します。上の 1 と 2 のコードはこの順になっています。処理に時間がかかる場合は、表に status(処理中・処理済み)と started_at を持ち、処理中のまま一定時間を過ぎたものは失敗とみなしてやり直せるようにします。Stripe のガイドも、未配信のイベントを手で処理するときに「処理中」と「処理済み」を分けて記録する例を示しています(Stripe)。

ID を持つ期間

送る側が同じイベントを送ってくる可能性がある期間より長く持ちます。

  • 自動の再送の期間(Stripe は本番で最長 3 日、Shopify は 4 時間)
  • 手動の再送ができる期間(Stripe はダッシュボードから 15 日、CLI から 30 日。GitHub は過去 3 日の配信を再配信できる)

出典は上の表の各社のドキュメントです。これらを合わせると、30 日から 90 日ほど持っておけば多くの場合に足ります。古い ID は日付で定期的に消します。

本文のハッシュを使わない理由

本文が同じでも別のイベントであることがあります。同じ金額の支払いが同じ秒に 2 回あった場合、ID 以外の中身が同じになることがあります。逆に、送る側によっては送るたびに本文の時刻などが変わることもあります。重複の判定には、送る側がイベントごとに付ける ID を使います。

順番の入れ替わりへの備え(イベントの時刻や版で古い更新を捨てる)は順番の入れ替わりの記事で扱います。

送る側が守ること

受ける側が ID で重複を除けるようにするには、送る側が次の 2 つを守る必要があります。

  1. イベントごとに一意の ID を付け、再送でも同じ ID を送る。
  2. 署名の対象に ID を含め、途中で ID を書き換えられないようにする。

Standard Webhooks は webhook-id を署名の対象(ID.時刻.本文)に含めていて、この 2 つを満たします。送る側が API に送信を頼むときの二重送信の防ぎ方(Idempotency-Key)は送信の API の Idempotency-Key の記事で扱います。

Webhook Admin から届く Webhook の場合

Webhook Admin は、1 つのメッセージに msg_… の ID を付け、webhook-id ヘッダーで送ります。再送や管理画面からの送り直しでも同じ webhook-id を付け、webhook-timestamp と署名だけを送るたびに作り直します。受ける側は、署名検証のドキュメントのとおり署名を確かめた後、webhook-id を一意制約つきで記録すれば重複を弾けます。自動の再送は既定では約 28 時間で終わりますが(送信先ごとの設定で最長 3 日)、配信の記録から手で送り直せるので、ID はプランの記録の保存期間(Free は 7 日、Starter は 30 日、Pro と Business は 90 日)より長く持っておきます。

送る側で webhook-id の付け方・再送・署名を自作せずに済ませたい場合は、Webhook Admin を無料で試せます(月 5 万通まで)。https://app.webhookadmin.com/signup

よくある質問

イベントの ID はどれくらいの期間保存すればよいですか。

送る側が同じイベントを送ってくる可能性のある期間より長く持ちます。自動の再送の期間だけでなく、手動の再送ができる期間も含めます。たとえば Stripe は自動の再送が最長 3 日、CLI からの手動の再送がイベントの作成から 30 日までです。

本文のハッシュで重複を見分けてもよいですか。

勧めません。本文が同じでも別のイベントであることがあり(同じ金額の支払いが 2 回あった場合など)、逆に同じイベントでも送る側によっては送るたびに本文の一部が変わることがあります。送る側が付ける ID を使います。

同じイベントが同時に 2 通届いたらどうなりますか。

「確認してから記録する」順番で書くと、両方が「まだ無い」と判断して 2 回処理されます。先に一意制約つきで ID を書き込み、書き込めた方だけが処理する形にすると、データベースが 1 通だけを通します。

関連記事