Webhook連携を外注する前に｜重複受信と再送の確認項目
Webhook連携の外注で通知の取りこぼしを防ぐため、署名・順序・重複・タイムアウト・再送・手動再処理・照合を見積前と納品時に確認し、追加範囲を判断する実務用の表です。
執筆・確認株式会社adding 編集部
order-guide / contract
Webhook連携を外注するときは、「通知を受け取って登録する」という一文だけで見積を依頼しないことが重要です。署名、通知の順序、重複、応答期限、失敗時の再送、手動再処理、配信履歴との照合を分け、それぞれを誰がどこまで担うか決めてください。
とりわけ、外部サービスが自動で再送するとは限りません。受信に成功しても後続処理が失敗する場合をどこまで扱うかによって、必要な実装と運用は変わります。見積前には正常系に加え、失敗した通知を発見し、正しい状態へ戻すところまで範囲を切り分ける必要があります。
ただし、すべてを受託側へ追加実装として依頼する必要もありません。外部サービスの管理画面やAPIでできること、発注者が手動で担えること、受信システムに必要なことを先に分ければ、追加範囲を判断できます。
Webhook連携を外注する前の見積項目表
次の表は、公式資料にある配信挙動を発注時の確認へ落とし込んだ、運用上の提案です。各行には対応の有無に加え、確認できる成果物と担当者まで記載します。
| 見積項目 | 見積依頼の前提として渡す内容 | 納品時に確認する内容 | 追加範囲と判断する条件 |
|---|---|---|---|
| 署名 | 対象サービス、検証に使うヘッダー、署名シークレットの受け渡し・保管担当 | 署名検証を行う時点と、検証前に受信本文を加工しない構成 | シークレットの発行・更新手順、環境ごとの切り替え、検証失敗の調査手順まで求める |
| 順序 | 通知が前後しても成立させる業務条件、不足データを取得できる手段 | 特定の到着順を前提にしていないこと。不足時の取得先と失敗時の扱い | 外部APIからの補完取得や、保留状態からの再開処理が必要 |
| 重複 | 重複とみなす識別子、処理済み記録の保持先、同じ対象への別イベントの扱い | 同じ通知を再度受けても業務処理を重ねないこと。判定記録を追えること | 複数種類の識別子を組み合わせる判定や、既存データとの突合が必要 |
| タイムアウト | 外部サービスが求める成功応答の期限、応答後に回せる処理の範囲 | 受信応答と時間のかかる業務処理を分けられること。応答後の失敗を検知できること | キューなどによる非同期化、監視、滞留した処理の回復が必要 |
| 再送 | 外部サービスの自動再送の有無、対象、終了条件 | 再送された通知にも重複排除が働くこと。再送の結果を確認できること | 標準の自動再送だけでは業務上の回復条件を満たせない |
| 手動再処理 | 実行者、対象の選び方、実行前の承認、実行結果の確認者 | 対象を誤らず選べること。同じ対象を再実行しても二重処理にならないこと | 管理画面、権限分離、承認記録、一括操作が必要 |
| 照合 | 比較する配信履歴と受信記録、差分を確認する担当、確認の契機 | 未受信・失敗・処理待ちを区別でき、差分から再送または調査へ進めること | 配信履歴取得APIとの連携、定期実行、対象外サービス向けの別手順が必要 |
この表で空欄が残った項目は、見積の前提条件または対象外として明記し、開発中の受託側の判断に委ねないようにします。とくに「外部サービス側の標準機能を利用する」とした行は、その機能が対象のWebhookで本当に使えるかを確認しなければ、復旧手段のない空白になります。
署名・順序・重複は、受信処理の入口で分ける
署名確認は、単に「対応する」と書くだけでは確認できません。2026年9月21日時点のStripe公式Webhook資料は、JSONペイロード、Stripe-Signatureヘッダー、Webhook署名シークレットを使う検証を案内し、検証に必要な受信本文を加工しないよう求めています。したがって見積書には、何を使って検証するか、いつ検証するか、検証前に本文を変えないかを一組で記載してもらいます。
納品時の確認対象には、正しい署名の受け入れに加え、署名を確認できない通知を業務処理へ進めないこと、その結果を調査できる形で残すことも含めます。シークレットの発行や更新、開発環境と本番環境の切り替えまで依頼するなら、受信機能とは別の納品範囲として線を引きます。
順序と重複も別々に決めます。同資料によると、Stripeはイベントの生成順で配信されることを保証せず、不足するオブジェクトはAPIで取得できるとしています。また、同じイベントを複数回受信する場合に備えて処理済みイベントIDを記録する方法を示し、同じ対象について別々のEventオブジェクトが生成される場合は、data.objectのIDとevent.typeの組み合わせで識別するよう案内しています。
ここから見積に落とす内容は、「順不同でも処理できるか」と「同じ処理を重ねないか」です。たとえば、必要な状態がまだ届いていないときに即座に失敗させるのか、外部APIから取得するのか、いったん保留するのかを決めます。どれを採用するかは運用上の選択です。受託側には、採用した条件と、回復できない場合に誰が確認するかを示してもらいます。
重複排除キーは「通知ID」とだけ書かず、イベント単位なのか、対象とイベント種別の組み合わせなのかを対象サービスの仕様に沿って特定します。処理済み記録があっても、どの業務処理が完了した状態を指すのか曖昧なら、再処理の判断に使えません。識別子、処理結果、再実行可否を同じ確認単位で追えることを納品条件にします。
タイムアウトは成功応答と業務完了を混同しない
2026年9月21日時点のGitHub公式Webhookベストプラクティスは、Webhook受信後10秒以内の2XX応答を推奨し、時間を超えると接続を終了して配信失敗として扱うと説明しています。非同期キューで応答と後続処理を分ける方法は推奨例であり、すべての連携で必須とされる方式ではありません。
10秒はGitHubについての推奨値です。依頼対象サービスの応答期限は見積前に個別に確認します。そのうえで、期限内に返す成功応答と、データ登録や後続処理の完了を分けて設計する必要があるかを判断します。
応答だけ成功し、その後の業務処理が失敗した場合、外部サービスからは配信成功に見える可能性を前提に、受信側で失敗を発見できる条件を置きます。ここで必要となる非同期処理、処理状態の記録、監視、手動回復は、単純な受信エンドポイントとは異なる追加範囲になり得ます。必要性を判断できない段階では、正常応答までを基本範囲、応答後の回復を選択範囲として分けて見積を依頼すると比較しやすくなります。
前提条件の整理方法はシステム要件定義の確認項目、基本範囲と選択範囲の見積の分け方はシステム開発見積の考え方もあわせて確認してください。
再送・手動再処理・照合を別の作業として決める
「失敗したら再送する」だけでは、外部サービスが行う再送と、受信側で行う再処理が混ざります。2026年9月21日時点では、Stripeには失敗配信の自動再試行と手動再送があります。一方、GitHub公式の失敗配信対応資料は、失敗配信を自動では再送せず、手動再送または利用者が用意する処理で対応すると説明しています。再送挙動はサービスごとに確認しなければなりません。
運用上は、次の三つを分けます。
- 再送：外部サービスから同じ通知をもう一度届ける
- 手動再処理：受信済みの記録を使い、受信側の業務処理をもう一度動かす
- 照合：外部サービスの配信履歴と受信側の記録を比べ、未受信や失敗を見つける
分ける理由は、入口と責任範囲が異なるからです。外部サービスからの再送ができても、すでに受信済みの通知を安全に処理し直せるとは限りません。反対に、受信側の手動再処理があっても、そもそも届いていない通知を見つける照合がなければ対象を選べません。
GitHubの同資料は、自動化する場合の例として、前回確認後に試行された配信をAPIで取得し、statusがOKでない配信を判定して再送する流れを示しています。ただし、GitHub MarketplaceとGitHub SponsorsのWebhookには配信データ取得APIがないとの例外も明記されています。これは推奨される手順の例であり、すべてのGitHub Webhookで同じAPIを使えるという意味ではありません。
そのため照合の見積では、取得する履歴の対象、前回確認地点の持ち方、失敗の判定、再送後の結果確認を分けます。対象サービスに履歴取得手段がなければ、管理画面での確認を発注者の運用に残すのか、受信側の記録だけで調査するのかを決めます。定期照合や自動再送まで求める場合は、追加実装として見積もります。
納品時は失敗から戻れることを確認する
納品確認では、通知が一度届いて登録できることに加え、判断表の各行に対応する失敗条件を選びます。順序が前後した通知、処理済み識別子と一致する通知、応答後に後続処理が失敗した記録、外部サービス側で失敗とされた配信など、依頼対象の仕様で再現できるものを確認します。
確認結果には、入力した通知を特定できる情報、受信結果、業務処理の状態、次に取る操作を残します。保存項目や画面は、発注者が「再送する」「受信済みの処理をやり直す」「調査へ回す」を選ぶために必要な範囲を納品条件にします。
見積を確定できるのは、署名・順序・重複・タイムアウトについて対象サービスの前提が明記され、再送・手動再処理・照合のどこまでを外部サービス、発注者、受託側が担うか決まった段階です。七項目の全実装を一律に求める必要はありません。通知の取りこぼしを防ぐ範囲を具体化できれば、標準機能で足りる部分と、追加実装または追加運用にする部分を同じ基準で判断できます。
費用、期間、契約、法務・税務上の扱いは条件により異なります。記事の確認日とリンク先の一次情報を確認し、個別判断は専門家へご相談ください。
システム開発・発注ガイドへ戻る