Webhookの設計とは｜連携の取りこぼしを防ぐ5つの仕様

はじめに

決済サービスでは入金済みになっているのに、社内の受注管理には反映されていない。手動で通知を再送すると、今度は発送依頼が二件できてしまった。これは説明用の例だが、Webhook連携で考えるべき境界がよく表れている。

Webhookは、外部サービスで起きたイベントをHTTPリクエストで受け取る仕組みだ。ただし、通知が一回だけ、発生順に、必ず届くとは限らない。届かない・重複する・順番が変わる場合まで仕様化する必要がある。

本記事では、受信側を設計する際に業務担当者と開発担当者が合意したい5つの仕様を整理する。特定サービスの実装方法ではなく、受信から業務への反映、障害後の照合までが対象だ。

受信の成功と業務処理の成功を分ける

Stripeの公式Webhookドキュメントは、イベント順序を保証しないこと、重複通知に対応すること、複雑な処理の前に速やかに成功応答を返すことを案内している。再送条件や署名方式はサービスごとに異なるため、これをすべてのWebhook共通の契約とみなしてはいけない。

受信側の設計例として、署名などを検証し、通知を永続化してから成功応答を返し、業務処理は別のワーカーで行う方式がある。ここでの成功応答は「通知を安全に受け付けた」であって、「発送まで完了した」ではない。

メモリ上のキューに入れただけで成功応答を返すと、その直後の停止で通知が失われる可能性がある。永続化に失敗した場合の応答と、業務処理が後から失敗した場合の復旧を分けておきたい。

連携の取りこぼしを防ぐ5つの仕様

以下は仕様検討のための設計提案だ。状態名や保存期間は、利用するサービスの契約と自社の業務に合わせて決める。

1. 署名検証と受信先の識別を決める

通知の本文だけを見て処理を始めず、送信元を検証する方式を確認する。Stripeの署名検証では、加工前のリクエスト本文、署名ヘッダー、エンドポイントの署名用シークレットが必要になる。JSONを整形してから検証すると、元の本文と一致しなくなる場合がある。

仕様には検証対象、許容する時刻差、鍵の保管先と更新手順を書く。鍵を記事やログに記録する必要はない。テスト環境と本番環境の識別も明確にし、別の顧客や環境の通知を誤って反映しないことを確認する。

不正な署名、本文の改変、期限外の通知をどう拒否するかは、提供サービスの検証方式に合わせる。署名が正しいことと、対象の注文を変更してよいことは別であり、テナントや対象IDの照合も必要だ。

2. 受信記録と成功応答の境界を決める

受信記録には、送信元、イベントID、受信時刻、対象ID、処理状態などを持たせる。本文を保存する場合は、個人情報の範囲、閲覧権限、保存期限を別途決める。調査に不要な機微情報を長期保存しない。

設計例では、記録の永続化が完了してから成功応答を返す。受付後の状態は「未処理」「処理中」「完了」「要確認」などに分け、ワーカーの途中停止を再開できるようにする。

受付の保存に失敗したとき、成功を返さないだけでは復旧が完結しない。送信側がどの応答を再送対象とするか、いつ再送を打ち切るかも確認する。自社の受信記録と送信側の配送記録を照合できることが重要だ。

3. 重複排除を業務処理までつなげる

同じイベントIDが再度届いた場合、受信側で二回目を認識できるようにする。判定範囲は、送信元・環境・テナント・イベントIDなど、IDの一意性が保証される単位に合わせる。並行した通知を単純な検索と追加だけで扱わず、一意制約などで競合を防ぐ。

ただし、別のイベントIDでも同じ業務対象の同じ変更を知らせる場合がある。イベントIDだけで十分か、対象IDとイベント種別などでも照合が必要かは提供側の契約を確認する。

さらに、通知を一回だけ受け付けても、その後の発送APIへの呼び出しが重複しないとは限らない。外部書き込みには業務上の操作キーと結果照合を用意する。この境界はAPIの冪等性で扱う仕様と結び付く。

4. 順序ずれと状態の競合を決める

「支払完了」の通知より先に「返金完了」が届くことも想定する。後から届いた古い通知で、返金済みの状態を支払済みに戻してはいけない。

状態遷移、バージョン番号、提供側の現在状態を取得する方法などから、どれを判断根拠にするかを決める。イベントの時刻だけで全体の順序を確定できるとは限らない。通知本文が発生時点のスナップショットか、現在状態を参照するための情報かも確認する。

判断できない通知は削除せず要確認にする。照会APIが失敗した場合を「対象がない」と扱わず、再照会や担当者への引き継ぎ条件を書く。

5. 再送と照合による復旧を決める

再送回数、間隔、保存期間、手動で再送できる期間は送信側の契約を確認する。自動再送と手動再送が重なる場合にも、同じ業務処理を増やさない設計が必要だ。

受信記録だけでは、まったく届かなかった通知を見つけられない。そのため、重要な業務では注文一覧や決済一覧など、正規システムの状態と照合する補完手順を検討する。照合範囲、実行間隔、担当者、差分を反映する権限を決める。

結果不明の書き込みを新しい操作として送り直す前に、対象IDや操作記録から結果を確認する。復旧ログには、何を照合し、何を再実行し、どこまで確認できたかを残す。

受け入れテストで確認すること

正常な通知が届くことだけでは、例外処理の仕様は確認できない。少なくとも次の条件を業務担当者と共有したい。

• 同じ通知を同時に二回送っても、業務上の登録が増えない。
• 受信記録の保存前に停止した場合は、再送で復旧できる。
• 受付後にワーカーが停止しても、未完了記録から再開できる。
• 古い通知が後から来ても、業務状態が不正に戻らない。
• 未配送の通知は正規システムとの照合で検出できる。
• 不正な署名や別テナントの対象を、業務処理へ渡さない。

連携先、方向、対象データの整理には外部インターフェース一覧を使い、通知ごとの受付と反映の条件を対応させるとレビューしやすい。

まとめ

Webhookの設計は、受信するURLを用意して終わりではない。検証、永続的な受付、重複排除、順序ずれ、照合による復旧を一つの業務フローとして確認する。

仕様を作る際は、通知を受けたことと業務が完了したことを分け、誰がどの記録で確認するかを明記したい。Kakusillなどの仕様書づくりの道具を検討する場合も、まずこの合意事項と受け入れ条件を整理することが出発点になる。