外部API連携の設計｜Webhook・再送・冪等性で“二重処理”を防ぐ

API連携は「繋がれば終わり」ではありません。
現場で問題になるのは、取りこぼし・二重処理・復旧不能の3つです。
Webhookが二回来た、タイムアウトで再送された、途中で落ちた、順序が逆になった…。
この記事では、外部連携を“運用として回す”ために必要な設計（冪等性、リトライ、ログ、監視）を整理します。

1. 前提：外部連携は「不安定で当たり前」

外部サービスは落ちます。ネットワークも揺れます。だから設計で吸収します。
「たまに失敗する」ではなく、「失敗しても復旧できる」が設計ゴールです。

• Webhookは再送される
• 同じイベントが複数回届く
• 順序が前後する（後のイベントが先に来る）
• 一部だけ処理が成功して中断する

この前提を受け入れると、必要な設計がはっきりします。

2. 冪等性：二重処理を“仕様で潰す”

冪等性とは、同じイベントを何回処理しても結果が1回に収束することです。
外部連携で最重要の考え方です。

状態遷移が絡むなら、ステータス運用（実例）と、禁止遷移（遷移図）がそのまま効きます。
「支払済」への遷移が二回走らない、などを状態側で防げます。

3. リトライ設計：失敗を“戻せる”形にする

連携処理は失敗します。だから、リトライ（再試行）を設計します。
ポイントは「どこまで成功したかが分かる」ことです。

• 入力：Webhook受信ログを保存（生データ）
• 処理：成功/失敗、エラー理由、再試行回数を記録
• 再処理：管理画面から再試行できる（権限付き）

この「再処理ボタン」があるだけで、復旧が劇的に速くなります。
権限・ログは 権限・ログ設計 に沿って、実行者と理由を残します。

4. 順序入替：イベントが前後しても壊れない状態設計

Webhookは順序保証がないことがあります。
そこで、状態遷移を「単純な一本道」にしないで、前後を吸収できる形にします。

• 「確定」より前に「通知」イベントが来ても、保留して後で確定に追随させる
• 後から来たイベントで“最新状態”に上書きするルールを決める
• 矛盾が出たら人が判断できるよう、ログと差分を残す

人が判断する導線は、管理画面の検索・フィルタ（絞り込み）とセットで作ると運用が止まりません。

5. 監視：障害に気づけないと復旧できない

連携は「失敗に気づける」ことが必須です。
通知の設計は 通知・リマインド の考え方で、次を決めます。

• 何回失敗したらアラート（例：3回連続）
• 誰に飛ばすか（運用担当、管理者）
• 何を見れば復旧できるか（ログ画面、再処理導線）

業種別の典型

ホテル（予約・決済・通知）

予約と決済、通知が絡むと、順序入替や二重処理が起きやすいです。
業務像は ホテル向けシステム開発例 を前提に、
予約カレンダー連携（関連：カレンダー×申込）では冪等性と再処理が必須になります。

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

外部の予約や通知サービスと繋ぐ場合、二重予約・二重入庫の事故が致命的です。
業務像は 自動車販売・整備・タイヤショップ向け を前提に、
入庫（関連：予約設計）やピット割当（詰まらせない設計）に影響が出ないよう、イベントIDで冪等性を固定します。

インテンスでも、連携部分は「成功時だけ見る」設計をやめ、失敗時の復旧導線（ログと再処理）を先に作ります。

まとめ

外部連携で守るべきは、二重処理と復旧不能を防ぐことです。
Webhook再送を前提に、冪等性を固定し、リトライ・ログ・再処理・監視までを一体で設計する。
これで、連携は“繋がるだけ”から“運用できる”状態になります。