Webhookの重複・順序・再実行｜自動化の受け取り仕様を作る

受信記録と業務完了を分ける

送信元へ応答する時点と、業務上の記録が確定する時点を図にします。後続の処理が長い場合は、途中で止まっても入力を追える記録が必要です。受け取ったID、元の発生時刻、受信時刻、対象、状態を区別し、失敗した処理を担当者が一覧から探せるようにします。

受け取ったという応答だけを、通知や書き込みの完了と見なさないでください。途中で失敗したときに、受付済み・処理中・完了・要確認のどこにいるか分かる構成なら、担当者が残りを調べやすくなります。

重複を見分けるキーを決める

重複判定のキーは、業務で何を一つの操作と扱うかによって決まります。注文番号だけでは、注文作成と発送更新を区別できない場合があります。一方、受付のたびに別の乱数を付けても、再送を見分ける助けにはなりません。送信元が維持するIDと、保存先の制約を合わせて設計します。

送信元が付けるイベントIDや、業務上の注文番号と操作種別を使う設計を検討します。Stripeのように冪等キーを扱うAPIもありますが、保存期間や再試行の条件は各APIで確認が必要です。

順序と同時実行を別に考える

順序が必要な対象を具体的に決めます。同じ注文の状態変更は順番が重要でも、無関係な注文すべてを一列に並べる必要はないかもしれません。処理が遅い一件で後続を止める影響と、並列処理で同じ記録を同時更新する影響を比較します。外部サービスまで一つの順序が保証されるとは考えないでください。

Makeの資料には並列処理と順序処理の説明があります。順序を守る設定があっても、複数の入口や外部サービスまで同じ順になるとは限らないため、更新対象の版や時刻の確認も検討します。

再実行で繰り返してよい範囲

タイムアウトの後は、外部側で実行されていないと決めつけません。受付番号などを使って相手側の結果を照会し、すでに完了した操作と未実施の操作を分けます。決済、在庫の増減、顧客への送信などは、単純な上書きと性質が違います。再実行の承認者と、確認できない時の保留手順を決めます。

決済や注文確定のように重複が問題になる操作は、再試行前に相手側の結果を照会する手順を設けます。安全性を一般論で保証せず、使い捨てデータで失敗位置ごとの挙動を確かめてください。

候補を選ぶための確認項目

採用前の確認表には、正常入力、同じIDの再送、古い更新の到着、書き込み直後の応答切れを入れます。実際の顧客へ通知しない検証先で、入力と最終記録を対応させて点検します。どの候補でも、担当者が失敗を発見し、再開位置を判断し、結果を説明できることが運用上の条件です。

Make・n8n・Activepiecesのどれでも、必要な保存・照会・再実行を担当者が管理できるかが採用条件です。最後に受付件数と完了件数を別集計で照合する手段を残します。

同じ注文通知が二回来る例

同じ注文の通知が続いた時は、重複の有無だけでなく、業務上許される状態遷移を確認します。作成前の発送や、取り消し後の確定など、古い情報で記録を戻さない判定が必要になる場合があります。見つからない注文を無条件で新規作成するのではなく、再取得や確認待ちに分ける方法も検討します。

判定キーをイベントID、または注文IDと操作種別の組み合わせとして設計し、どちらを使えるか送信元の仕様を確認します。最初の処理が完了していない間に二回目が来る場合も考え、確認と書き込みの競合が起きない保存方法を選びます。

元の業務記録へたどれるIDを使い、保持期間と再処理が必要になったときの手順を決めます。外部APIの冪等処理だけで、自分の台帳や通知まで一括で守れるとは考えないでください。

• 業務自動化ツールの選び方｜最初の仕事を決める比較手順
• Makeとn8nを比較｜日次集計と明細処理、運用費で選ぶ
• 問い合わせフォームを自動化する｜受付から担当者の対応まで