顧客案件のWebhook連携は、重複・再送・通知が来ない場合までどこまで任せるか
- 2 日前
- 読了時間: 13分
SIerや開発会社が顧客案件のWebhook連携を外部へ任せる場合、受信用APIを1本作れば終わるとは限りません。
重複や処理失敗への対応だけでなく、通知そのものが来なかった場合に正しい状態をどう確認するかまで含めて責任範囲を決めることが重要です。
はじめに：Webhookは「受け取れたら完了」ではない
外部サービスとの連携には、大きく分けて「こちらからAPIを呼び出す方式」と「外部サービスから通知を受け取る方式」があります。
Webhookは後者です。
たとえば外部サービス側で、
決済が完了した
契約状態が変更された
ファイルの処理が完了した
ユーザー情報が更新された
といったイベントが発生したとき、あらかじめ登録しておいたURLへ通知が送られます。
定期的に外部APIを呼び出して変更を確認する必要がなく、イベントを起点に処理を開始できる便利な仕組みです。
ただし、顧客案件でWebhook連携を実装する場合には、
「通知を受け取るAPIを作る」
だけを外注範囲にすると、実運用で必要になる部分が抜けることがあります。
Webhookでは、通信失敗、タイムアウト、同じ通知の再送、処理途中のエラーなどを考慮する必要があります。送信元サービスによって、再送条件や通知順などの仕様も異なります。
さらに、業務によっては**「通知が来なかったときに、外部サービス側の正しい状態をどう確認するか」**まで考える必要があります。
そのため、外注するときは**「Webhookエンドポイントを作る」という機能名ではなく、「通知を安全に受け取り、業務処理へ反映し、失敗や通知欠落が起きても正しい状態へ復旧できるところまで」のどこを任せるか**で考えることが重要です。
API連携全般の外注時に整理したい内容については、API連携開発を外注するときに確認すべきポイントでも解説しています。
結論：Webhook連携は4つの範囲に分けて考える
Webhook連携を外注するときは、開発範囲を次の4つに分けると整理しやすくなります。
1. 受信する
外部サービスから送られたWebhookを受け取る部分です。
たとえば、
Webhook受信用URLの実装
認証・署名の検証
イベント種別の判定
ペイロードの形式確認
などが含まれます。
2. 重複や再送に耐えられるようにする
同じイベントが複数回届いても、同じ業務処理を重複実行しないようにする部分です。
たとえば決済完了通知を2回受信したからといって、
同じ注文を2回確定する
同じポイントを2回付与する
同じメールを2通送る
といった結果になってはいけません。
3. 業務システムへ反映する
受信したWebhookをもとに、
注文状態を更新する
会員情報を更新する
後続処理を開始する
必要に応じて外部APIから最新状態を取得する
といった業務処理を行う部分です。
4. 失敗した処理を復旧できるようにする
Webhookの受信には成功したものの、その後のDB更新や外部API呼び出しに失敗するケースもありま
す。
そのときに、
自動的に再処理するのか
管理機能などから再実行するのか
担当者へ通知するのか
外部サービス側の状態と照合するのか
通知自体が来なかった可能性をどう確認するのか
まで決めておきます。
顧客案件としてバックエンド部分を外注するなら、この4つのうちどこまでを一つの成果物として任せるのかを明確にすることが重要です。
最初に決めたいのは「どこまでできたら受信成功なのか」
Webhook設計で見落とされやすいのが、送信元へ成功レスポンスを返すタイミングです。
単純に考えると、
Webhookを受信↓DBを更新↓別システムのAPIを呼ぶ↓メールなどの後続処理を行う↓すべて終わったら成功レスポンス
としたくなるかもしれません。
しかし、後続処理が増えるほど処理時間は長くなり、その途中で何かが失敗する可能性も高くなります。
そのため、重要なWebhookでは、
Webhookを受信
↓
通知内容を検証
↓
後から処理できる状態で確実に保存
↓
送信元へ成功レスポンス
↓
業務処理を実行
というように、通知を受け付ける処理と、その後の業務処理を分ける設計を検討します。
ここで重要なのは、「業務処理がすべて終わった」ことと「Webhookを確実に受け付けた」ことは同じではないという点です。
この境界が曖昧だと、障害が起きた際に、
通知そのものを受け取れなかったのか
通知は受け取ったが保存できなかったのか
保存はできたが後続処理に失敗したのか
が分かりにくくなります。
外注時には、単に「Webhook APIを作る」ではなく、どの時点を受信完了とするかまで仕様に含めると責任範囲が明確になります。
筆者が決済連携で実際に扱ってきた「通知だけを信用しない」設計
筆者は、決済結果を非同期通知で受け取り、その結果をもとに業務状態を更新するシステムの開発に携わってきました。
その際、単に「成功通知が来たから決済成功」「通知が来ていないから決済失敗」と判断するのではなく、届いた通知の内容や、そもそも通知が来ているかどうかを材料に、必要に応じて決済サービスの外部APIへ問い合わせ、実際の決済状態を改めて確認する処理も設計しています。
非同期決済では、システム側の通信だけを考えればよいわけではありません。
たとえばエンドユーザーが決済画面へ進んだものの、
認証途中で画面を閉じた
ブラウザの戻る操作をした
決済途中で離脱した
決済事業者側では処理が進んだが、自社システムの完了画面まで戻らなかった
といったケースもあります。
このようなケースでは、画面上の遷移結果だけでも、Webhookの有無だけでも、業務上の最終状態を正しく判断できないことがあります。
そのため、決済のように結果が業務や金銭へ直結する連携では、
「通知が来たか」
だけではなく、
「外部サービス側では最終的にどの状態になっているか確認できるか」
まで含めて設計することが重要です。
重複対策は「同じ通知を無視する」だけではない
Webhookでは、同じ内容の通知が再び届く可能性を考慮して設計します。
代表的な方法は、送信元から提供されるイベントIDや配信IDなどを記録し、
「このイベントはすでに処理済みか」
を確認してから業務処理を実行する方法です。
たとえば、
Webhookを受信する
イベントIDを確認する
未処理なら記録する
業務処理を実行する
処理済みに更新する
という流れです。
ただし、ここでも送信元サービス側の仕様確認が必要です。
サービスによっては、再送時も同じ識別子が使われる場合もあれば、同じ業務上の出来事に対して別のイベントが通知される可能性を考慮すべき場合もあります。
そのため、
イベントID
イベント種別
注文IDや契約IDなどの業務キー
現在の処理状態
のどれを使って重複を判断するのかを決めます。
重要なのは、「Webhookが1回しか来ないこと」に期待するのではなく、「複数回来ても結果が壊れないこと」を目標にすることです。
外部サービスの仕様自体が不明確で、イベントIDや再送条件などがまだ判断できない段階では、先に仕様調査を切り出す方法もあります。外部APIの仕様が不明確な案件でも、バックエンド部分を外注できるのかで、その進め方を解説しています。
「送信元からの再送」と「受信後の再実行」は分けて考える
Webhookの「再送」という言葉には、異なる処理が混ざりやすいため注意が必要です。
Webhookそのものが届かなかった
たとえば、
サーバーが停止していた
ネットワークエラーが発生した
タイムアウトした
受信用URLがエラーを返した
といったケースです。
送信元サービスに再送機能があれば、一定の条件でWebhookが再度送られることがあります。
これは送信元サービス側の再送です。
Webhookは受け取ったが、業務処理に失敗した
Webhook自体は受信・保存できたものの、
DB更新でエラーになった
顧客システム内の別機能との連携に失敗した
別の外部APIが一時的に停止していた
といったケースです。
この場合は、送信元にWebhookを再送してもらうのではなく、受信側で保存したイベントや処理情報を使って、失敗した業務処理を再実行する方法を検討します。
たとえば処理状態を、
受信済み
処理中
処理成功
処理失敗
などで管理し、失敗したものだけを再実行します。
障害後に取りこぼしがないか確認する
さらに、長時間の障害などから復旧した後には、
「本当にすべてのイベントを処理できているのか」
を確認する必要が出ることもあります。
送信元にイベント履歴や現在状態を取得するAPI・管理機能がある場合には、Webhookだけに頼らず、外部サービス側の状態と照合する方法も検討できます。
つまり、障害時には、
送信元からの再送受信側での業務処理の再実行障害復旧後の外部サービスとの照合
を分けて考える必要があります。
通知された順番どおりに処理できるとは限らない
Webhookを業務システムへ反映するときには、通知の順番も確認します。
たとえば、あるデータについて、
作成
更新
完了
というイベントが外部サービスで発生したとしても、受信側が必ずその順番で処理できることを前提にしてよいかは、送信元サービスの仕様によります。
並列処理や再送などが絡むと、古いイベントが後から処理される可能性も考慮する必要があります。
もし受信順だけを見て無条件にDBを更新すると、
完了
↓
古い更新イベントを処理
↓
完了前の状態へ戻る
といったことも考えられます。
順序が業務上重要な場合には、
更新日時やバージョンを比較する
現在の状態から許可される状態遷移だけを受け付ける
外部APIから最新状態を取得して確認する
同じ注文や契約単位で処理順を制御する
などの方法を検討します。
イベントを受信することと、そのイベントをそのまま現在状態として採用することは別です。
具体例：決済完了Webhookを「受信APIだけ」で切り出すと何が足りないか
たとえば、ECや予約システムへ決済サービスを組み込み、決済結果をWebhookで受け取る案件を考えます。
悪い切り方
外注仕様が次だけだとします。
「決済完了Webhookを受け取り、注文を支払済みに更新するAPIを実装する」
一見すると明確ですが、実際には次の点が決まっていません。
同じ決済完了通知が2回来たらどうするのか
Webhook受信後、DB更新に失敗したらどうするのか
通知が一度も来なかったらどうするのか
ユーザーが決済途中で離脱した場合はどう判断するのか
決済サービス上の状態と注文状態が食い違ったらどうするのか
後から失敗した処理を再実行できるのか
正常系のデモは動いても、本番運用で問題が起きた際に誰の責任範囲なのかが曖昧になります。
整理された切り方
たとえば成果物を、
「決済結果Webhookの受信から、注文状態への安全な反映と失敗時の再処理まで」
と定義し、内訳として、
Webhook受信・検証
イベントIDによる重複防止
受信イベントの保存
注文との対応付け
必要に応じた決済状態確認APIの呼び出し
注文状態の更新
処理失敗時の再実行
処理結果を追跡するログ
まで含める方法があります。
さらに、
「決済サービス側との障害後の一括照合は対象外」
など、今回実装しない範囲も明記します。
こうすると、元請け・外注先の双方が「Webhook連携一式」という言葉から異なる範囲を想像することを防ぎやすくなります。
4つの範囲をそのまま見積内訳に落とす
Webhook連携を見積もるときも、冒頭で整理した4つの範囲をそのまま使えます。
範囲 | 主な実装・確認内容 |
1. 受信する | Webhookエンドポイント、認証・署名検証、イベント判定、ペイロード検証 |
2. 重複や再送に耐える | イベント保存、重複判定、処理状態管理、必要に応じた非同期化 |
3. 業務システムへ反映する | 既存DB更新、業務状態変更、外部APIによる状態確認、後続処理 |
4. 失敗した処理を復旧する | エラーログ、再実行、監視・通知、通知欠落の確認、障害後の照合 |
すべての案件でこの全機能が必要なわけではありません。
重要なのは、どこまでが今回の見積に入り、どこからが対象外なのかを明文化することです。
たとえば、
1〜3は今回実装する
4のうち自動再実行まで実装する
運用担当者向けの管理画面は対象外
外部サービスとの一括照合機能は別途
という切り方もできます。
バックエンド開発全体の責任範囲については、バックエンド開発を外注するとき、責任分界はどう決めるべきかでも詳しく解説しています。
検収条件には正常系だけでなく異常系を入れる
Webhook連携では、正常に1回通知を受け取れることだけを検収条件にすると不十分な場合があります。
業務上重要なWebhookであれば、たとえば次のような確認項目を検討します。
同じイベントを複数回受信しても業務処理が重複しない
不正な署名や認証エラーの通知を受け付けない
一時的な後続処理エラーから再処理できる
処理済み・未処理・失敗を追跡できる
通知順が前後しても不正な状態へ戻らない
1件のイベントについて受信から処理結果まで追跡できる
必要な場合に失敗した処理を再実行できる
必要な業務では、通知が来ない場合も外部サービス側の状態を確認できる
こうしたテストケースを最初から成果物へ含めると、
「実装は終わったが、障害時にどうなるか分からない」
という状態を避けやすくなります。
どこまで堅牢にするかは、Webhookが扱う業務で決める
すべてのWebhook連携へ同じレベルの仕組みを入れる必要はありません。
たとえば、多少取りこぼしても大きな問題にならない補助的な通知と、
決済完了
注文確定
契約状態変更
会員権限変更
では、失敗したときの影響が異なります。
後者のようにイベントの取りこぼしや重複処理が、業務データや金銭へ直接影響する処理ほど、受信履歴、重複防止、再処理、状態照合までを外注範囲へ含める価値が高くなります。
反対に、重要度の低い通知へ過剰な仕組みを入れれば、開発費と運用負荷だけが増えます。
発注時には、
「このWebhookを1件取りこぼしたら何が起こるか」「同じイベントを2回処理したら何が起こるか」
「通知が来なかった場合、正しい状態を別の手段で確認できるか」
を確認すると、必要な堅牢性を判断しやすくなります。
仕様が固まっていない場合は、調査と実装を分ける
顧客案件では、
Webhook仕様は公開されているが、詳細まで確認できていない
既存システム側のどこを更新すべきか分からない
再送仕様や認証方式をまだ確認していない
既存コードを見ないと影響範囲を判断できない
という段階で外注先を探すこともあります。
その場合、最初から固定した実装範囲で請負契約にする必要はありません。
まず、
外部サービスの仕様確認
既存システム調査
イベントと業務状態の対応整理
重複・失敗・再処理方式の設計
実装範囲と責任分界の確定
という調査・整理工程を切り出し、その結果をもとに実装工程を成果物単位で発注する方法があります。
実務では、Webhook周辺だけをバックエンド成果物として切り出すこともできる
顧客案件全体を一社へ任せる必要はありません。
たとえば元請け側で、
顧客との要件調整
フロントエンド
インフラ全体の管理
を担当し、外部の開発会社へ、
Webhook・API仕様の調査
既存システムの影響調査
Webhook受信設計
重複・再処理を考慮したバックエンド設計
既存DB・業務ロジックへの組み込み
試験
を成果物単位で切り出す方法もあります。
プレイリーソリューションズでは、Java / AWSを中心としたバックエンド開発、API・決済連携、既存Webシステム改修などを扱っており、Webhook連携についても、受信用APIだけではなく周辺の業務処理を含めて範囲を整理できます。
仕様が完全に確定していない場合には、まず調査・設計部分を小さく切り出し、実装範囲を確定してから成果物単位の請負開発へ進めることも可能です。
まとめ：Webhook連携の外注範囲は「通知が来なかった後」まで考える
Webhook連携を外注するときは、受信用エンドポイントの有無だけではなく、
どこまでできたら受信成功とするか
重複したイベントをどう扱うか
業務処理に失敗したらどう再実行するか
通知順が前後した場合にどう扱うか
通知が来なかった場合にどう正しい状態を確認するか
障害後にどう復旧・照合するか
どこまでを外注先の責任範囲とするか
まで整理しておくことが重要です。
特に非同期処理では、「通知が来たかどうか」だけで最終結果を判断できるとは限りません。
まずは、
「このWebhookを取りこぼしたら困るか」「2回処理したら困るか」「通知が来なかったとき、別の方法で正しい状態を確認できるか」
を整理してください。
そこから必要な重複対策、再処理、状態照合のレベルを決めると、過不足のない外注範囲を作りやすくなります。
SIer・開発会社の方で、顧客案件のAPI・Webhook連携やバックエンド部分を成果物単位で切り出したい場合は、プレイリーソリューションズへご相談ください。要件整理・技術調査から、設計・実装・試験まで対応します。
