トラッキングWebhookエンドポイントは何を返すべきか?ステータスコード、タイムアウト、リトライについて?
A tracking webhook endpoint should return a fast, intentional 2xx response after it has accepted the event for processing. ほとんどの統合では、リクエストを認証し、ペイロードを検証し、イベントを保存またはキューに入れ、200 OKまたは202 Acceptedで応答するパターンが最も安全です。送信元が再試行すべきでないリクエストには4xxレスポンスを使用し、一時的なサーバー側の問題によって受け付けられなかった場合は5xxレスポンスを使用します。正確なタイムアウトや再試行の動作はWebhookプロバイダーの契約に依存するため、実装は推測ではなく、文書化された送信元の動作を基準に設計してください。
トラッキングまたは配送ステータスのWebhookでは、配送イベントが複数回到着したり、順不同で到着したり、ネットワーク障害後に再送されたりする可能性があるため、この区別が重要です。エンドポイントの役割は、必ずしもすべての業務処理を応答前に完了させることではありません。まず重要なのは、イベントを受け付けたかどうかを信頼性の高い方法で判断することです。
実務におけるレスポンス契約
Webhookレスポンスには、送信システムと自社アプリケーションという2つの受け手がいます。送信元は、配送を成功として記録するか、再試行するか、停止するかを判断するために、明確なHTTP結果を必要とします。アプリケーション側は、イベントを検証して永続的に記録するための十分な時間を必要とします。エンドポイントに短い同期処理と、分離された非同期処理の経路を設けると、これらの目標を達成しやすくなります。
- HTTPS経由でHTTPリクエストを受信する。
- プロバイダーが要求する署名、認証情報、タイムスタンプ、その他のリクエスト完全性制御を確認する。
- 時間のかかる下流処理を行わずに、ペイロードを解析して検証する。
- イベント、または重複排除レコードとイベント参照情報を、永続ストレージまたは信頼できるキューに書き込む。
- 意図した2xxレスポンスを返す。
- トラッキング更新、顧客通知、在庫変更、その他の業務処理を非同期で実行する。
イベントがプロセスメモリにしか存在しない場合、レスポンスで受け付けたと主張してはいけません。成功を返した直後にアプリケーションがクラッシュすると、永続化されていないイベントが失われ、送信元は配送が成功したと判断してしまいます。したがって、2xxを返す時点は、実際の耐久性保証と一致させる必要があります。
Webhookはどのステータスコードを返すべきか?
| レスポンス | 送信元にとっての意味 | 一般的なWebhookでの用途 |
|---|---|---|
200 OK | リクエストが受け付けられ、正常に処理された。 | 検証と永続的な受け付けの後に返す実用的なデフォルト。 |
202 Accepted | リクエストは処理対象として受け付けられたが、処理は継続する可能性がある。 | イベントを安全にキューへ入れたものの、業務処理が非同期の場合に有用。 |
204 No Content | リクエストは成功し、レスポンス本文は不要。 | プロバイダーが空の成功レスポンスを受け付ける場合に適切。 |
400–499 | リクエストが無効、認証されていない、または送信された形式では受け付けられない。 | 不正なペイロード、認証失敗、無効な署名、恒久的に拒否されたイベント。 |
429 Too Many Requests | 受信側がレート制限を適用している。 | 送信元の再試行動作と自らのレート制限ポリシーに互換性がある場合のみ使用。 |
500–599 | サーバー側または一時的な問題のため、受信側がリクエストを受け付けられなかった。 | データベース障害、キュー障害、依存サービス障害、予期しないアプリケーションエラー。 |
200 OKは成功した受信を広く意味するため、最も予想外のない選択肢であることが多いです。エンドポイントがイベントを後で処理するために受け付けた場合は、202 Acceptedも意味的に有用です。ただし、どちらのコードも自動的に正しいとは限りません。送信元のドキュメントで、どの2xxレスポンスを成功とみなすかが定義されている場合があり、特定の本文やコンテンツタイプを要求するプロバイダーもあります。
HTTPリクエストがサーバーに到達したという理由だけで、2xxレスポンスを返してはいけません。署名検証に失敗した場合や、ペイロードを安全に解釈できない場合は、通常4xxレスポンスの方が正確です。一方、一時的なデータベース障害に対して4xxを返してはいけません。後でイベントを成功させられる可能性があるためです。5xxレスポンスを返せば、再試行可能な送信元がイベントを再度配送する機会を得られますが、プロバイダーが独自のポリシーを適用する場合があります。
タイムアウトはどのように処理すべきか?
Webhookのタイムアウト値はプロバイダーごとに異なります。すべてのトラッキングプラットフォームで使われる普遍的なHTTPタイムアウトは存在せず、アプリケーションが時間のかかる処理を終える前に送信元が待機を止めることもあります。送信元が文書化しているタイムアウトを目標ではなく最大境界として扱ってください。通常、エンドポイントはその境界より十分前に応答すべきです。
最も一般的な設計上の誤りは、Webhookを確認する前にすべての下流処理を行うことです。ハンドラーがデータベース、注文管理システム、通知サービス、分析パイプラインを順番に呼び出すことがあります。1つの依存先が遅いだけで、アプリケーションが最終的に処理を完了しても、送信元にはタイムアウトとして認識される可能性があります。その結果、送信元が再試行し、重複処理や競合する更新が発生することがあります。
同期処理は、安全に受け付ける判断に必要な処理に限定してください。通常は、リクエスト認証、基本的なスキーマ検証、イベントの永続保存、キューへの登録が含まれます。高コストな情報補完、配送業者への照会、顧客へのメッセージ送信、サードパーティAPI呼び出しはワーカーの背後で実行してください。イベントの受信、検証、永続化、応答にかかった時間と、処理にかかった時間を分けて監視します。
タイムアウトは、業務処理が失敗したことと同じではありません。送信元から見ると、タイムアウトは通常、利用可能な成功レスポンスを受信できなかったことを意味します。接続が閉じる直前に、サービスがイベントを正常に保存している場合もあります。そのため、エンドポイントが信頼できるように見える場合でも、冪等性と重複排除が必要です。
再試行が発生する原因
Webhookの送信元は、接続エラー、タイムアウト、または契約上失敗と分類されるレスポンスの後に再試行することがあります。正確な間隔、最大試行回数、バックオフアルゴリズム、配送期間はプロバイダーによって異なります。プロバイダーのドキュメントに記載されていない限り、固定回数の再試行を約束しないでください。
受信側は再試行が起こり得ることを前提に、意図的に設計すべきです。
- 利用可能な場合はイベント識別子を使用する。一意制約または同等の重複排除キーとともに保存する。
- 処理を冪等にする。同じ配送ステータス更新を2回適用しても、顧客へのメッセージを2通送信したり、2回返金したり、注文を誤って進めたりしないようにする。
- 元のペイロードまたは有用な監査記録を保持する。再実行、調査、照合に役立つ。
- 受け付けと処理を分離する。ワーカーが内部障害を再試行できるようにし、送信元にHTTP通信全体を繰り返させない。
- レスポンスコードと遅延を記録する。5xx、タイムアウト、重複イベントIDの増加から、ユーザーがトラッキング更新の欠落を報告する前に障害を発見できる。
元のイベントがすでに永続的に受け付けられている場合、重複イベントには通常、成功レスポンスを返すべきです。すべての重複にエラーを返すと、不要な再試行が発生する可能性があります。エンドポイントはイベントが以前に確認済みであることを記録し、重複した業務処理をスキップして、新たに受け付けたイベントに使用するものと同じ成功クラスを返せます。
4xx、429、5xxはいつ返すべきか?
同じリクエストを再試行しても問題が解決する可能性が低い場合は4xxを返します。無効な署名、必須認証の欠落、サポートされていないペイロード形式、恒久的な検証ルールに違反するリクエストなどが例です。4xxを選ぶ前に、送信元がそのステータスを恒久的な失敗として扱うか確認してください。
429は慎重に使用してください。HTTPではレート制限に429を定義しており、Retry-Afterヘッダーで再試行が適切になる時期を伝えられます。ただし、すべてのWebhook送信元が429を同じ方法で解釈するわけではありません。キューが満杯またはサービスが過負荷の場合は、プロバイダーが安全に再試行するか、再試行スケジュールが過負荷を悪化させないかを確認してください。
一時的な問題により受信側がイベントを安全に受け付けられない場合は5xxを返します。利用できないデータベース、永続キューへの書き込み失敗、検証または永続化を妨げる内部エラーなどが該当します。イベントを黙って破棄しながら200を返すと、送信元が再試行する理由を失うため、復旧が難しくなります。
Webhook配送で301、302、307などのリダイレクトに依存することは避けてください。リダイレクトの処理はクライアントによって異なり、署名付きリクエストをリダイレクトすると、宛先、メソッド、本文について曖昧さが生じる可能性があります。代わりに、最終的なHTTPSエンドポイントをプロバイダーに設定してください。
トラッキングイベントの信頼できるレスポンスポリシー
ほとんどのトラッキングWebhook統合では、次のポリシーが適切な出発点になります。
- イベントが認証を通過し、永続的に保存されたか信頼できるキューに入れられた後に、
200または202を返す。 - 無効な署名、無効な認証、恒久的に使用できないペイロードには、プロバイダーの文書化されたルールに従って4xxを返す。
- 一時的な障害により永続的な受け付けができない場合は5xxを返す。
- 安全に認識できる重複には成功レスポンスを返し、重複した業務効果は防止する。
- ハンドラーを高速に保ち、応答遅延を測定する。
- 本番稼働前に、タイムアウト、再試行、重複、順不同、不正形式、プロバイダー障害のシナリオをテストする。
トラッキングAPIを統合する場合は、まずプロバイダーのWebhookドキュメントを確認し、受け付けられる成功コード、リクエスト署名方式、タイムアウト、再試行のトリガー、ペイロードスキーマ、イベント識別子を確認してください。17TRACK統合では、一般的なHTTPの慣行から推測するのではなく、プロバイダー固有の契約を確認するために公式Tracking APIドキュメントを参照してください。
実装チェックリスト
- エンドポイントがHTTPS経由で到達可能で、安定した本番URLを持っている。
- 認証と署名検証が業務処理の前に行われる。
- 署名確認とトラブルシューティングに必要な場合、元のリクエストまたは検証可能な表現を保持している。
- 成功レスポンスを送信する前にイベントが永続化される。
- 重複配送が安全で、不可逆な処理を繰り返さない。
- ワーカーが送信元のHTTP再試行サイクルとは独立して内部処理を再試行できる。
- ログにイベントID、配送時刻、レスポンスコード、処理状態、相関IDが含まれ、秘密情報を公開していない。
- アラートがエンドポイントのタイムアウト、4xx検証失敗、5xx障害、キュー遅延、重複配送を区別している。
- 文書化されたプロバイダーの動作を、実際のイベントまたはサンドボックスイベントでテストしている。
FAQ
Webhookでは200 OKと202 Acceptedのどちらがよいですか?
どちらが普遍的に優れているわけではありません。リクエストを受け付け、統合側でレスポンスを一般的な成功として扱う場合は200 OKを使用します。イベントを非同期処理のために受け付けた場合は202 Acceptedを使用します。送信元が選択した2xxレスポンスを成功と分類することを確認してください。
Webhookエンドポイントはトラッキング更新が完全に処理されるまで待つべきですか?
通常は待つべきではありません。イベントが認証され、検証され、永続的に受け付けられるまでだけ待つべきです。長時間の処理は通常、応答後に行い、遅い依存先によって回避可能なタイムアウトや再試行が発生しないようにします。
同じトラッキングイベントが2回届いた場合はどうすべきですか?
プロバイダーのイベントIDまたは慎重に設計した同等のキーで認識し、重複した副作用をスキップします。イベントがすでに受け付けられている場合は成功レスポンスを返してください。これにより、新たな処理失敗を隠すことなく再試行を安全に処理できます。
無効な署名には400と401のどちらを返すべきですか?
選択は認証モデルとプロバイダーが文書化している期待値によって異なります。どちらも拒否を伝えられますが、どちらかを普遍的に選ぶことより一貫性が重要です。真正性を検証できないイベントを受け付けてはいけません。
5xxレスポンスは必ず再試行を引き起こしますか?
いいえ。多くのWebhookシステムはタイムアウトやサーバーエラーを再試行しますが、再試行のトリガーとスケジュールはプロバイダーによって異なります。再試行を文書化された統合動作として扱い、テスト環境で確認してください。
出典
- RFC 9110: HTTP Semantics — 成功、クライアントエラー、サーバーエラー、リダイレクト、レスポンス処理の定義。
- RFC 6585: Additional HTTP Status Codes —
429 Too Many Requestsの仕様。 - Stripe Webhooks Documentation — Webhookレスポンス、非同期処理、重複イベント処理に関する実践的なガイダンス。
- GitHub Docs: Handling Webhook Deliveries — Webhook統合における配送確認と運用上の考慮事項。
- 17TRACK Tracking API Documentation — トラッキングAPI統合時に確認すべきプロバイダー固有のドキュメント。


