ブログ · · 約 9 分で
Webhook の重複と冪等性:webhook-id・一意制約・処理済みの記録
Webhook が
要点
- 送る
側は 「少なくとも 1 回」 届ける 設計なので、 同じ イベントが 2 回以上 届く ことは 避けられません。 - 受ける
側は、 イベントの ID を 一意 制約つきで 記録し、 入らなければ 2 回目として 処理を 飛ばして 2xx を 返します。 - ID の
場所は 送る 側ごとに 違います (webhook-id、 Stripe の event.id、 GitHub の X-GitHub-Delivery、 Shopify の X-Shopify-Webhook-Id など) 。
Webhook を
冪等性とは
冪等性
重複が起きる理由
- 受け取ったが、
2xx が 。送る 側に 届かなかった 処理を 終えて 応答を 返す途中で 接続が 切れると、 送る 側からは 失敗に 見えます。 - タイムアウトの
後に 。処理が 終わった 送る 側は タイムアウトで 失敗と 記録しますが、 受ける 側では 処理が 最後まで 進んでいます。 - 送る
側の 。障害や 手動の 再送 送る 側の キューが 同じ 仕事を 2 回実行する、 運用者が 記録から 送り直す、 と いった 場合です。
Shopify も
各社の「同じイベント」を見分ける ID
2026-09-27 に
| 送る |
ID の |
再送で |
補足 |
|---|---|---|---|
| Standard Webhooks | webhook-id ヘッダー |
同じ | 仕様が |
| Stripe | 本文のidevt_…) |
同じ | 別々にdata.object のtype で |
| GitHub | X-GitHub-Delivery ヘッダー |
再配信でも |
配信ごとの |
| Shopify | X-Shopify-Webhook-Id ヘッダー |
― | 配信ごとのX-Shopify-Event-Id は |
| Slack | 本文のevent_id |
記載なし | すべてのx-slack-retry-num ヘッダーが |
| LINE | 本文のwebhookEventId |
― | 再送のdeliveryContext.isRedelivery が |
出典: Standard Webhooks の
Shopify のX-Shopify-Webhook-Id、X-Shopify-Event-Id です。
3 つの守り方
1. 一意制約による除外
いちばん単純な
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);
});この
2. 同じトランザクションでの記録と業務の更新
業務の
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,
]);
}); // 途中で失敗すれば両方とも取り消され、次の再送でやり直せる処理の
3. 何度実行しても同じ結果になる処理
INSERT … ON CONFLICT DO UPDATE
逆に
同時に 2 通届いたとき
再送の
先にstatusstarted_at を
ID を持つ期間
送る
- 自動の
再送の 期間 (Stripe は 本番で 最長 3 日、 Shopify は 4 時間) - 手動の
再送が できる 期間 (Stripe は ダッシュボードから 15 日、 CLI から 30 日。 GitHub は 過去 3 日の 配信を 再配信できる)
出典は
本文のハッシュを使わない理由
本文が
順番の
送る側が守ること
受ける
- イベントごとに
一意の ID を 付け、 再送でも 同じ 。ID を 送る - 署名の
対象に ID を 含め、 途中で ID を 書き換えられないように する。
Standard Webhooks はwebhook-id をID.時刻.本文)Idempotency-Key)
Webhook Admin から届く Webhook の場合
Webhook Admin は、msg_… のwebhook-id ヘッダーでwebhook-id をwebhook-timestamp とwebhook-id を
送るwebhook-id の
よくある質問
イベントの ID はどれくらいの期間保存すればよいですか。
送る
本文のハッシュで重複を見分けてもよいですか。
勧めません。