注文が二重登録されるのはなぜ？Webhook連携で再送しても重複させない方法

相手は受け付けた。でも、こちらには返事が届かなかった

説明用の例として、決済完了の通知を受け、倉庫へ出荷指示を送る連携を考えます。倉庫は指示を登録したものの、その応答が通信途中で失われたとします。送信側にはタイムアウトが表示されますが、倉庫には既に指示があります。新しい番号で送り直せば、相手は別の指示として受け付けるかもしれません。

このとき「失敗だから再送」は成り立ちません。まず結果が分からない状態として記録し、倉庫の指示番号や外部注文番号から調べます。すぐ検索して出てこないことも、未登録の証拠になるとは限りません。相手側の反映に時間がかかるなら、確認まで待つ必要があります。業務担当者がこの状態を見分けられることが、安全な復旧の入口です。

Webhookは、一回だけ届く前提にしない

Webhookは、注文や決済などの変化を相手へ知らせる通知です。送信元が受領の応答を確かめられない場合などに、同じ通知が再び届くことがあります。Stripeの公式資料も重複配送と到着順の不確実さを説明しています。通知が再送されたら仕事まで繰り返す設計では、一時的な通信の揺らぎが二重登録につながります。

受信側では、まず署名を検証します。Stripeでは未加工のリクエスト本文を使い、検証に失敗した通知は重複判定用の記録へ入れません。正当な通知だけを対象に、通知IDの重複判定と後から処理できる内容の永続保存を行い、その後に受領応答を返します。「署名検証→重複判定と永続保存→受領応答」の順です。保存前に成功を返すと、直後の停止で通知を失うおそれがあります。重い業務処理は保存後の別工程で進め、未処理を追えるようにします。

参考：Stripe：Receive Stripe events in your webhook endpoint

通知が違っても、同じ注文を動かしていることがある

注文確定と決済完了という別々の通知から、同じ出荷を指示してしまう場合があります。通知IDが違うため、通知の重複だけを見ていても防げません。店舗、注文、出荷する単位などを組み合わせて、何を同じ仕事とみなすかを決めます。分納を扱うなら、注文番号だけで「一度済んだら禁止」とすると、必要な二回目の出荷まで止めてしまいます。

また、二つの処理が同時に未実行と判断する競合にも備えます。データベースの一意制約や条件付き更新などで、同じ仕事を実行する権利を重ねて取れないようにします。完了だけでなく処理中も記録し、途中停止したものをどう調べるかを決めます。「実行前に検索しています」という説明に加えて、同時に届いたときの結果を確かめるのが要点です。

冪等性は、送り直しても仕事を増やさないための仕組み

冪等性は、同じ操作を繰り返しても結果を重ねない性質です。外部APIが冪等キーを受け付けるなら、同じ仕事の再試行には同じキーを使います。毎回別のキーを作ると、相手には別の操作に見えます。StripeのAPIではキーに対応する結果を保存しますが、保持や適用には条件があり、期限を超えた再実行まで無条件に守られるわけではありません。

金額や対象を変えた訂正は、同じ操作のやり直しとは区別します。古いキーを流用すればよいとは限りません。自社側でも、どの業務操作をいつ試し、結果がどうなったかを保持します。連携先に重複防止や結果照会の手段がなければ、人が確認する範囲を残す設計も必要です。相手の仕様を超えた無人復旧を約束しないことが、依頼範囲を決めるうえで重要になります。

参考：Stripe：Idempotent requests

待てば直る問題と、止めて確認する問題を分ける

アクセスが集中した一時的な制限と、住所の必須項目が空欄という入力不備は、同じ再試行では解決しません。前者は待機、後者は入力修正が必要です。AWS SDKの資料には、再試行の上限や待ち時間をばらつかせる考え方が示されています。一斉に送り直して相手へ負荷をかけないように、使うSDKと自社処理の双方の挙動を確認します。

業務上の締め切りも上限になります。いつまでも自動で待つと当日の出荷に間に合わないなら、途中で担当者へ知らせます。下表は判断の例で、実際には連携先の応答と処理の意味を合わせて決めます。HTTPの番号だけで、更新が実行されたかまで断定しないことが大切です。

表が収まらない場合は横にスクロールできます。

参考：Amazon Web Services：Retry behavior - AWS SDKs and Tools

依頼先には、わざと途中で止める試験を頼む

正常な一件だけでは重複対策を評価できません。同じ通知の同時到着、古い通知の遅着、保存直後の停止、外部登録後の切断を試します。取消済みの注文を古い確定通知で戻さないこと、処理が増えず未処理だけ残ることを確認します。最新状態を取得して判断する案もありますが、途中の出来事を一件ずつ扱う業務は、それを省いてよいか別に検討します。

復旧の実演には、担当者が手入力で補った場面も入れます。自動処理を再開したときにその結果を認識できなければ、同じ重複が起こるためです。見積もりでは受信処理に加え、結果照会、保留一覧、手動復旧、漏れを探す照合の範囲を確かめます。二重登録を防ぐ仕組みと同じくらい、「今どの注文がどうなっているか」を人が説明できることが大切です。

検討・発注前のチェックリスト

担当者と確認状況を添えて、社内の検討メモや打ち合わせの議題にご活用ください。

確認日：________________ / 担当者：________________

• □通知IDと業務の識別子を分ける。確認状況・メモ：
• □分納や訂正を同じ仕事と誤認しない単位を決める。確認状況・メモ：
• □通知の同時到着を試験に含める。確認状況・メモ：
• □登録直後の通信切断で結果を照会できるか試す。確認状況・メモ：
• □再試行の上限と担当者へ戻す期限を決める。確認状況・メモ：
• □手入力で補った結果を自動処理へ反映する。確認状況・メモ：
• □古い通知と取りこぼしを照合できるようにする。確認状況・メモ：

よくある質問

参考資料

製品の仕様・提供条件は変更されることがあります。採用時には公式資料と契約内容をご確認ください。

• Receive Stripe events in your webhook endpointStripe
• Idempotent requestsStripe
• Retry behavior - AWS SDKs and ToolsAmazon Web Services