冪等性と再試行の設計｜Webhook/API連携で二重処理・取りこぼしを防ぐ

業務システムが外部サービスと連携すると、必ず起きるのが「二重に処理された」「届いてない」「順番が入れ替わった」です。
この問題は、運用で根性対応しても終わりません。システム側に再試行と冪等性（同じイベントを複数回受けても結果が同じになる性質）を組み込む必要があります。
本記事では、Webhook/API連携で壊れない設計の考え方を、実務の観点で整理します。

1. 二重処理は“バグ”ではなく仕様として起きる

外部連携では、次の理由で同じイベントが複数回届きます。

• 外部側が「届いたか分からない」と判断して再送する
• 受信側がタイムアウトして、外部側が失敗扱いにする
• 内部の再実行（ジョブ再起動、手動リトライ）
• ネットワーク分断による遅延到着（順番が入れ替わる）

つまり、二重をゼロにするより「二重でも事故にならない」設計に寄せる方が現実的です。

2. 冪等設計の基本：処理済み管理（冪等キー）を“業務キー”で持つ

冪等性は、受信イベントに付与される一意ID（イベントID）だけでなく、業務側のキーでも守ると強くなります。
例として、次のようなキーを組み合わせて「処理済み」を持ちます。

• イベントキー：外部イベントID（あれば最優先）
• 業務キー：注文番号、問い合わせ番号、予約番号など
• 操作キー：支払い確定、キャンセル、返金などの種別

問い合わせや予約のようにステータス遷移が多い場合は、ステータス運用と整合する形で「同じ遷移を二回受けても同じ状態になる」ように作るのが基本です。

3. 再試行（リトライ）の設計：即時リトライと遅延リトライを分ける

再試行は無限にやると事故になります。段階設計にします。

• 即時リトライ：数回（例：3回）だけ短い間隔で再実行
• 遅延リトライ：バックオフ（間隔を伸ばす）で数回（例：最大24時間）
• 打ち切り：最終的に「手作業キュー」へ落とす

打ち切った後に必要なのは「どこまで進んで、何が失敗したか」が分かるログです。ここは 監査ログ設計 と同様、追記・理由・エラー内容を残すと復旧が早くなります。

4. 失敗を“見える化”する：手作業に落とすための画面とルール

再試行が尽きたら、現場が処理できる形に落とす必要があります。最低限次を用意すると運用が回ります。

• 失敗イベント一覧（日時、対象、エラー、再試行回数、現ステータス）
• 再実行ボタン（冪等キーを守ったまま再実行）
• スキップ/手動反映（上長承認が必要な場合も）

この「失敗一覧」は、問い合わせ管理の保存ビュー（フィルタ設計）と同じ発想で作ると、運用担当に説明しやすいです。

5. 連携が絡むときの“担当割当”の注意点

外部連携で問い合わせや予約が自動登録されると、担当割当も自動化されがちです。
ただし、担当割当は例外が多いので、自動・手動・混在の割当 を前提にし、連携登録時点では「仮割当」にする設計も現実的です。

業種別に事故りやすい連携（例）

物流（納品予約・受付枠）

予約枠や受付枠は、二重計上がそのまま現場混乱になります。業務像は 物流向け を前提に、冪等キーを「予約番号＋日時＋バース」など業務キー寄りで強化すると事故が減ります。

自動車販売・整備・タイヤショップ（予約・入庫・部品手配）

連携で予約や入庫が自動登録されると、二重登録が“当日の詰まり”に直結します。業務像は 自動車販売・整備・タイヤショップ向け を前提に、冪等性と再試行を必須要件として握るのが安全です。

まとめ

外部連携は、二重処理と取りこぼしが必ず起きる前提で設計すると安定します。
冪等キーで処理済み管理を持ち、再試行は段階化し、最後は手作業に落とす画面とルールを用意する。ログは追記で説明できる形に寄せる。
これを組み込むだけで、運用開始後の「なぜ二重になった？」が大幅に減ります。インテンスでも、連携がある案件はこの設計を最初から要件に入れる方が結果的に安く済みます。