通知が重複・逆順・遅延したとき、連携を立て直す

同じ通知が二度届く、順番が変わる、結果が分からない場合を、具体例と再開手順で整理します。

目次

通知の結果が分からないときは、送信元の記録と受信先の処理結果を照合し、処理されていない分だけを再実行します。 結果を調べられないものは保留し、担当者が確認します。

Webhookは、あるサービスで起きたことを別のサービスへ知らせる通知です。「顧客情報を変更したらCMS側へ知らせる」などに使います。通知が届かなかったのか、処理した後の返事だけが届かなかったのかで、次の対応が変わります。ここでは連携を作る際の設計を説明します。EmDashの標準機能だけですべて対応できるとは限りません。

このガイドで整理するのは、連携を作る担当者へ渡す「届かなかったときの扱い」です。運用担当者は、送信元の配信履歴と受信先の受付記録を案内してもらい、どの通知がどう処理されたかを見比べます。コードの修正や障害の再現は制作担当者が行います。

同じ通知が二度届く場合

たとえば受付番号A123の登録通知が二度届いても、問い合わせを二件作らないようにします。通知を見分けるIDと処理済み記録を保存し、同じIDの通知が再び届いたら、処理を繰り返さず前と同じ結果を返す仕組みを検討します。

同じ操作を繰り返しても、1回実行した場合と同じ結果になる性質を「冪等性(べきとうせい)」と呼びます。二つの通知がほぼ同時に来ると、どちらも「まだ処理していない」と判断する場合があります。開発担当者は、データの保存先であるデータベースに同じIDを二つ登録できないようにする制限(一意制約)や、登録と処理結果を一緒に確定する方法を設計します。

古い通知が後から届く場合

顧客が「旧住所→新住所」と変更した後に、旧住所の通知が遅れて来ることがあります。到着順だけで上書きすると、元へ戻ってしまいます。

相手の版番号を照合する、対象の最新状態をAPI(データを受け渡す窓口)から読み直す、といった方法を選びます。別サーバーの時刻だけで順序を保証できるとは限りません。通知順が保証されない例はStripeの公式資料(別タブで開く)にもありますが、保証内容は利用中の送信元ごとに確認します。

受け取ったことと、処理完了を分ける

受信した内容を確実に保存してから受付を返し、その後で処理する設計なら、重い処理を受信中にすべて終わらせずに済みます。ただし、保存前に受付成功を返し、その直後にプログラムが停止すると、通知を失う可能性があります。

受信時には、正しい相手から来たか、途中で内容が書き換わっていないかを確認します。このために使われるものが認証や署名です。これらの確認、保存の完了、実際の更新を、それぞれ追える記録が必要です。秘密情報(接続用の鍵など)や顧客情報の全文をログ(動作記録)へそのまま残さず、通知IDと処理結果など、確認に必要な情報を記録します。

結果が不明なら、先に相手を照合する

タイムアウトは、決めた時間内に返事がなかった状態です。必ず失敗したという意味ではありません。受付番号などで相手の登録結果を確認し、未処理だけを再実行します。

状態次の対応
受付前に失敗したと確認できた条件を直して再送する
相手では処理済み重複実行せず結果を記録する
結果を調べられない保留へ分け、担当者が確認する

たとえば送信元では「A123は応答なし」でも、受信先にA123の受付が残っていれば、処理は済んでいる可能性があります。番号と処理結果を両側で確かめるまで、もう一件を作り直さないようにします。

上限と再送の間隔を決める

APIの利用上限を、他の既存連携と共有している場合があります。失敗直後に全件を連続再送すると、相手の回復を妨げることがあります。

再送するたびに待ち時間を延ばすか、何回まで再送するかを決めます。処理しきれない通知を保留する場所と、担当者への連絡先も決めておきます。上限や再試行の指示は、利用先の応答と公式資料に合わせます。

止まったところから再開する練習

制作担当者が本番と分けた検証環境で、同じ通知の二度送信、順序を入れ替えた送信、途中停止、認証失敗を再現し、完了・未処理・結果不明の件数を確認します。相手の最新データと突き合わせてから、保留分を少数ずつ再開します。復旧後の照合にもこの記録を使います。

公式の参照元

関連ガイド

メニュー
ホーム公式ドキュメント (別タブで開く)

キーワードを入力すると、ガイドの内容から探せます。