Webhookによる出荷追跡：トラッキングWebhookの仕組みとポーリングの比較（ペイロード、再試行、セットアップ）

配送追跡Webhookは、追跡サービスに報告すべき更新があると、アプリケーションにHTTPリクエストを送信します。ポーリングはその逆方向で、アプリケーションが最新の追跡情報を繰り返しリクエストします。配送データを注文管理システム、ストア、または顧客通知サービスに接続する開発者にとって、Webhookがサポートされている場合、一般的にはWebhookが主要な更新メカニズムとして適しています。対象を絞ったポーリングは、受信できなかった更新の回復や記録の照合に役立ちます。

どちらの方法でも、配送業者による荷物のスキャンが早まるわけではありません。どちらも、追跡情報の提供元が新しい情報を受信して公開するタイミングに依存します。実際の違いは、アプリケーションがその情報をどのように取得するか、どれだけのリクエストトラフィックを発生させるか、そして配信に失敗した場合に何が起きるかです。

追跡Webhookとポーリングの比較：運用上の違い

これらは統合パターンであり、競合する追跡データベースではありません。配送業者や追跡プラットフォームは、どちらか一方、または両方のパターンを、異なる利用条件で提供する場合があります。すべてのWebhookサービスが同じ保証を共有していると仮定せず、利用予定の具体的なAPIの動作を比較してください。

タイムリーな更新が重要で、信頼性の高い受信側を運用できるチームがある場合は、Webhookを優先してください。 インバウンドエンドポイントの運用が難しい場合、配送量が少ない場合、または情報源が適切なWebhookを提供していない場合は、ポーリングを優先してください。 更新漏れが顧客とのコミュニケーションや業務を妨げる可能性があり、APIが照合をサポートしている場合は、ハイブリッド設計を使用してください。

Webhookの方が安価だと決めつけないでください。サブスクリプション料金、追跡登録、API呼び出し、イベント配信、インフラストラクチャは、異なる方法で課金される可能性があります。リクエスト数が少ないことを低料金の証拠とみなすのではなく、実際の商用条件と予想される作業量を比較してください。

配送業者のスキャンからアプリケーションまでの間に何が起きるか

1. 配送を識別する。追跡番号、必要に応じた配送業者情報、社内配送参照番号を関連付けます。一部のサービスでは、監視を開始する前に登録が必要です。
2. イベント配信を設定する。HTTPSコールバックURLを提供し、サポートされているイベントサブスクリプションを選択します。
3. 情報源が追跡情報を受信する。配送業者のスキャンまたはステータス変更が追跡サービスで利用可能になります。
4. サービスがWebhookを送信する。リクエストには、追跡情報の完全なスナップショット、単一のチェックポイント、またはAPI参照が必要な参照情報だけが含まれる場合があります。
5. 受信側が検証して保存する。リクエストを認証し、構造を確認して、イベントを永続的に記録またはキューに追加します。
6. ワーカーが業務システムを更新する。ステータスを正規化し、配送記録を更新し、現在も適切なアクションだけを実行します。

Webhookの配信は、物理的な配送と同じものではありません。これは配送情報に関するメッセージです。同様に、Webhookへの正常な応答は、メールが送信されたことや注文記録が更新されたことを証明するものではありません。これらは下流の処理結果であり、独自の監視が必要です。

追跡Webhookペイロードの読み方

以下のJSONは、統合設計の例示であり、17TRACKのペイロードや普遍的なスキーマではありません。実際のフィールド名、ステータスコード、タイムスタンプ形式、イベント識別子は、選択したプロバイダーのドキュメントに従う必要があります。

{
  "event_id": "evt_example_001",
  "event_type": "shipment.updated",
  "created_at": "2025-04-08T10:16:00Z",
  "shipment": {
    "reference": "shipment_example_123",
    "tracking_number": "EXAMPLE123456",
    "carrier_code": "example_carrier",
    "status": "in_transit",
    "checkpoint": {
      "occurred_at": "2025-04-08T10:10:00Z",
      "description": "Departed processing facility"
    }
  }
}

データモデルでは3つの時刻を分けて管理してください。配送イベントが発生した時刻、プロバイダーがメッセージを生成した時刻、アプリケーションが受信した時刻です。遅延したチェックポイントが新しいチェックポイントの後に到着することがあります。オフセットのないタイムスタンプにも明示的な解釈が必要です。すべての配送業者の現地時刻を暗黙的にUTCとして扱わないでください。

プロバイダーの識別子とともに、社内配送参照番号も保持してください。特に異なる配送業者のコンテキスト間では、追跡番号だけでは永続的なグローバル識別子として不十分な場合があります。分割注文では、1つの荷物の配達完了ステータスによって注文全体が完了扱いにならないよう、注文単位ではなく配送単位の記録を維持してください。

正規化した業務ステータスとともに、元のステータスと説明も保持してください。アプリケーションが複数の配送業者メッセージを「輸送中」にマッピングする場合でも、サポートスタッフが遅延を理解するために元のチェックポイントを必要とすることがあります。配達予定日はあくまで予測として扱い、フィールドが欠落している場合と、既存の値を消去する明示的な指示を区別してください。

リトライ、確認応答、重複イベント

Webhookの配信は、タイムアウト、ネットワーク中断、認証エラー、または受信側の利用不能によって失敗する可能性があります。プロバイダーがリトライする場合もありますが、普遍的なリトライスケジュール、保持期間、最大試行回数はありません。どの応答が再試行を引き起こすのか、リダイレクトがどのように処理されるのか、手動での再配信が可能かを確認してください。

永続的に受け入れた後で確認応答を返す

リクエスト経路は短く保ってください。リクエストを検証し、受け入れた処理を永続化して、プロバイダーが要求する成功応答を返します。メール送信や時間のかかる業務処理は非同期で実行してください。HTTP仕様では、202 Acceptedは処理完了ではなく処理の受け入れを意味しますが、プロバイダーによっては別の成功応答を要求する場合があります。そのWebhook契約に従ってください。

何も保存せずに成功を返すと、プロセスがクラッシュした際に更新を失う危険があります。すべての下流アクションが完了するまで待つと、タイムアウトして再配信が発生する危険があります。永続的なインボックスまたはキューによって、受信と処理の間に境界を設けられます。

処理を冪等にする

冪等性とは、同じイベントを再度処理しても、業務上の効果が重複して発生しないことです。サーバーがイベントを受け入れた後、確認応答が失われたために送信側がリトライすることがあります。そのため、重複配信を通常のテストケースとして扱う必要があります。

• 利用可能な場合は、文書化されたイベント識別子を重複排除キーとして使用し、正しいプロバイダーまたはアカウントの範囲に限定します。
• 識別子が存在しない場合は、安定したイベントフィールドから複合キーを設計し、衝突リスクをテストします。
• ストレージ上で一意性をアトミックに強制します。別々の「確認してから挿入」処理は、同時配信時に競合する可能性があります。
• 下流のアクションも保護してください。重複イベントによって配達通知が再送されたり、金融アクションが繰り返されたりしてはいけません。
• 重複排除記録をすぐに削除するのではなく、プロバイダーの再生動作と復旧要件に応じて保持期間を設定します。

時系列順に到着すると仮定しない

リクエストが最後に到着したという理由だけで、現在の配送状態を上書きしないでください。イベントの意味、タイムスタンプ、文書化されたシーケンス情報を比較します。遅れて到着したチェックポイントは履歴に保持し、表示ステータスを自動的に後戻りさせないでください。同時に、文書化された訂正は許可してください。配達済みの配送は決して変更されないという厳格なルールでは、正当な例外や訂正情報を隠してしまう可能性があります。

実践的な設定チェックリスト

1. プロバイダーの契約を確認する

実装前に、登録要件、サポート対象イベント、ペイロード形式、認証、応答要件、タイムアウト、リトライ動作、API制限を確認してください。通知がスナップショットを表すのか増分変更を表すのか、配信に複数のレコードを含められるのか、購読時に初期状態が送信されるのかを確認します。

17TRACKとの統合では、公式のTracking API pageとAPI documentationから始めてください。リクエストフィールドとコールバック要件を確立するには、プロバイダー固有のドキュメントを使用してください。上記の汎用ペイロードは代替にはなりません。導入予定の統合について、アクセス条件と運用上の制限を確認してください。

2. 受信エンドポイントを保護する

HTTPSと、プロバイダーが文書化している認証メカニズムを使用してください。HMAC署名を使用する場合は、指定された署名対象の入力を正確に検証します。生のリクエストバイトに署名する場合、検証前にJSONを解析して再シリアライズするとバイト列が変わり、署名が無効になる可能性があります。秘密情報から生成された署名値の比較には、一定時間比較を使用してください。

署名付きタイムスタンプや配信識別子を利用できる場合は、文書化されたリプレイ対策を適用してください。有効な署名はメッセージを認証しますが、それだけでメッセージが新しいことを示すものではありません。秘密情報をURLやアプリケーションログに含めないでください。秘密情報のローテーションをサポートし、リクエストサイズを制限してください。IP許可リストは、維持されたアドレス範囲が存在する場合に追加の制御として利用できますが、メッセージ認証の代替ではありません。

3. 受信と業務処理を分離する

受け入れたイベントを追跡し、安全に再生するために十分な情報を保存します。キューワーカーは更新を正規化し、状態遷移ルールを適用して、アクションの結果を記録します。繰り返し失敗する処理は、無期限にリトライするのではなく、確認可能なデッドレターワークフローに移します。追跡ペイロードには顧客関連情報が含まれる場合があるため、アクセスと保持期間を制限してください。

4. リリース前に障害経路をテストする

• 同じイベントを、同時配信を含めて2回送信します。
• 新しいチェックポイントの後に古いチェックポイントを配信します。
• キューの停止と、受信後のワーカークラッシュをシミュレートします。
• 無効な認証、不正なJSON、サイズ超過リクエストをテストします。
• 存在しない配送、欠落した任意フィールド、追加されたフィールドをテストします。
• 1つの配達済み荷物によって分割注文全体が完了扱いにならないことを確認します。
• 復旧後にイベントを再生し、通知が重複排除されたままであることを確認します。

安全な場合は追加フィールドに寛容であるべきですが、未知のステータス値を黙って別の意味に解釈しないでください。元の値を保持し、認識できないケースを定義済みのフォールバックまたは確認プロセスに振り分けます。

ポーリングが今も有効な場面

ポーリングは、初期同期、障害後の復旧、予想される更新が届いていない配送の確認に役立ちます。ただし、沈黙だけでWebhookの失敗を証明できるわけではありません。荷物に本当に新しいスキャンがない場合もあります。静かな配送すべてにアラートが必要だと仮定するのではなく、APIの現在の状態または履歴と照合してください。

規模計画では、簡略化したポーリングモデルは、1リクエストにつき1配送と仮定すると、1時間あたりのリクエスト数 ≈ アクティブな配送数 × 配送1件あたりの1時間のポーリング回数です。バッチエンドポイントを使用すると、この計算は変わります。例として、1,000件の配送を1時間に4回確認すると、リトライ前で1時間あたり4,000リクエストが発生します。これは算術上の例であり、プロバイダーの割当量や料金見積もりではありません。

配送の活動状況と業務上のリスクに応じて確認をスケジュールし、レート制限を尊重して、ジョブがすべて同時に開始されないようジッターを追加してください。リトライ可能な失敗には、上限付きのバックオフを使用し、適用可能なサーバーの指示に従います。永続的な認証エラーや検証エラーは、修正せずに繰り返しリトライしないでください。

実用的なハイブリッドシステムでは、通常の更新にWebhookを使用し、更新漏れが疑われる場合に対象を絞ったAPI読み取りを行います。受信失敗、キューの経過時間、処理失敗、重複率、照合不一致をそれぞれ個別に監視します。タイムスタンプが信頼できる場合は、情報源のデータ遅延、Webhook配信遅延、内部処理遅延を区別してください。

FAQ

追跡Webhookはリアルタイムですか？

次のポーリングサイクルを待つことによる遅延を短縮できる場合があります。ただし、配送業者によるスキャンが即座に行われることや、情報源が瞬時に更新されることを保証するものではありません。エンドツーエンドの最新性には、配送業者による報告、プロバイダーの処理、リクエスト配信、アプリケーション自体が含まれます。

Webhookを有効にした後、ポーリングを完全に停止できますか？

プロバイダーの復旧機能と業務要件上、それで問題ない場合は可能です。ただし、業務上重要な配送記録については、照合方法を保持してください。すべての配送を継続的にポーリングするのではなく、対象を絞った方法にできます。

Webhookエンドポイントがオフラインになるとどうなりますか？

復旧方法は、送信側の文書化されたリトライポリシーによって異なります。リトライが無期限に続くと仮定しないでください。エンドポイントを復旧した後、失敗した配信を確認し、サポートされている再配信ツールを使用して、可能であればAPI経由で影響を受けた配送を照合してください。

すべてのWebhookで顧客通知を発生させるべきですか？

いいえ。イベントが重複している場合、過去のチェックポイントである場合、または顧客向けステータスを変更しない更新である場合があります。通知は、重複排除された業務上の状態遷移から発生させ、例外や訂正のルールを設けてください。

HTTPの正常な応答は、配送更新が完了したことを意味しますか？

必ずしもそうではありません。非同期設計では、合意された契約に基づいて受信側がイベントを受け入れたことを意味します。受け入れられたリクエストによってワークフローの失敗が隠れないよう、処理の完了と下流の通知結果を別々に追跡してください。

Sources

• RFC 9110: HTTP Semantics — 処理の受け入れやRetry-Afterを含む、HTTP応答の意味論。
• RFC 2104: HMAC—Keyed-Hashing for Message Authentication — 署名検証のガイダンスで参照されているHMAC構造。
• GitHub Docs: Best practices for using webhooks — HTTPS、秘密情報、非同期処理、配信識別に関する一般的なエンジニアリングガイダンス。サービス固有のルールは配送プロバイダーの動作を定めるものではありません。
• 17TRACK Tracking API — 17TRACK追跡統合を評価するための公式エントリーポイント。
• 17TRACK API documentation — 実装要件に関するプロバイダー固有のリファレンス。