Tracking Webhook API

Mutation.registerTrackWebhookを通じて、運送状の状態変化が発生した時、ユーザーが登録したURLにCallbackを受け取ることができます。

基本的な手順

登録・登録解除

会員登録

運送状の追跡を開始するには、まず[Mutation.registerTrackWebhook](/docs/api-schema/api/mutations/register-track-webhook](/docs/api/schema/api/mutations/register-track-webhook)を使用して carrierId, trackingNumber, callbackUrl, expirationTime を登録する必要があります。

ヒント

carrierId がわからない場合は、まず Tracking API のドキュメントをご覧ください。

callbackUrl は、運送状の状態が変更されたときに応答を受け取りたいユーザーのサーバーのURLを入力してください。 デリバリートラッカーで当該URLにRequestを転送します。

expirationTime` は ISO8601 規格に従い、一般的な場合、現在時刻から 48 時間後の時間を使用することを推奨します。 詳しくは本書の「Webhook Keep Alive」を参照してください。

Try (GraphQL)

HTTP

cURL

Code

Query (GraphQL)

Variables

をクリックして応答を確認することができます。

インフォメーション

上のTry Runボタンを使ってテストする場合、ユーザーのプロジェクトに接続されないため、Consoleでデバッグすることができません。 別途クライアントコードを作成して認証後、HTTP Requestを呼び出すことでConsoleでデバッグすることができます。

登録解除

Mutation.registerTrackWebhookの expirationTimeに未来の時間ではなく現在の時間を渡すことで、明示的にWebhookの登録を解除することができます。

しかし、このように明示的にAPIを呼び出して明示的に登録解除するよりも、TTLの満了によって自動削除させることをおすすめします。 詳しくは、本書の「Webhook Keep Alive」パートを参照してください。

コールバックハンドラの実装

DeliveryTracker Webhookシステムが運送状に変化を検知すると、登録された Callback URL に次のような Request を送信します。

POST {callbackUrl}
content-type: application/json

{
  "carrierId"："{carrierId}",
  "trackingNumber"："{trackingNumber}"
}

Callback には carrierId と trackingNumber だけが渡され、 この情報をもとに Query.track を使ってユーザーが欲しい情報を調べることができます。

代表的な実装方法

状況に合わせて二つの実装方法のどちらかを選択してCallback Handlerを実装することができます。

方法1. Callback Queue による処理

Callback Handler内で別のQueueにTrackingNumberを入れておいて、 別のWorkerでQueueに積まれたTrackingNumberを読んでQuery.trackを呼び出す方法を推奨しています。

方法2. Callback Handler内でQuery.trackを直接呼び出します。

Queue処理が状況的に難しい場合は、Callback Handler内で直接Query.trackを呼び出す方法もあります。 ただし、この方式は基本的な実装は簡単ですが、トラフィックが多い場合、実装方法1に比べて比較的TimeoutとRateLimitの複雑さが増す可能性があります。

コールバック応答コードとリトライ

Callback の実装は、Response を 1 秒以内に渡し、Response Status Code に 202 (Accepted) を送ることを推奨します。

Callback Url の HTTP Response Status Code が 2XX でない場合、内部 Exponential Backoff Retry ロジックに従って expirationTime に達するまで継続的に再試行します。

ヒント

継続的に Callback エラーが発生したり、 expirationTime が短くて expirationTime が期限切れになる状況を防ぐために、定期的に expirationTime を更新してください。 詳しくは Webhook Keep Alive をご覧ください。

Webhook Keep Alive

追跡を希望する運送状番号が生じた場合、現在時刻の48時間後の未来時刻をexpirationTimeとして使用し、expirationTimeを定期的(24時間ごと)に更新することをお勧めします。

24時間に一度ずつ追跡を継続しなければならない運送状番号リストについて、 Mutation.registerTrackWebhook を 再度呼び出し(expirationTimeを現在時刻+48時間)することをお勧めします。

これにより、引き続き追跡すべき対象は引き続きexpirationTimeが増加し、追跡対象でない場合は48時間後に自動的に登録解除することができます。

このような方法を使用して、Register と Unregister の順番を間違えて送信して、意図せずに Unregister したり、永遠に Register 状態のままになってしまう状況を回避することができます。

テスト

実際の運送状に変更が発生するまで待つには、かなりの時間（n時間からn日）がかかります。

ヒント

Dummy Tracking Number を使用する方法も存在します。

このような時間を短縮するため、Delivery Tracker Consoleのプロジェクト内の「Webhook」メニューでは、 登録されたWebhookリストと「Callback Call Test Trigger」ボタンをクリックしてCallback呼び出しQueueにCallback呼び出しを要求することができます。

このように発生した Callback は、通常は n 分以内に処理され、運送状のステータスが変更されていなくても送信されます。

注意事項

Query.trackをpollingするよりもTrack Webhookを使うことの利点は何ですか？

デリバリートラッカーの内部最適化ロジックに従って効率的に動作するように設計されています。

例えば、一般的な場合、Callbackが発生した直後にQuery.trackを呼び出す場合、Tracking dataがキャッシュされているので、Query.trackをpollingして使用するよりも短いレイテンシーで使用することができます。 また、polling周期などpolling時に発生する様々な状況を気にする必要がなくなり、Callback発生時のみTrack APIを呼び出してTrack APIの呼び出し頻度を減らしてRate Limitを効率的に使うことができます。

Callbackの発生は保証されますか？

expirationTimeに達しない限り、運送状の状態が変更された場合、Callback発生が保証されます。 (最初の初期化時にも Callback が発生します). 内部Retryロジックに従って定期的にRetryします。

警告

expirationTimeまで成功しない場合、一度も送信できず削除される可能性がありますので、expirationTimeの管理にご注意ください。 詳しくは「Webhook Keep Alive」をご覧ください。

API Rate Limitにご注意ください。

プロジェクトに指定された API Call Rate Limit に注意してください。

キューに入れて使用してください。

Callback内にtrack apiの呼び出しを実装するより、Callbackでは別のQueueに変更事実を伝えて別のWorkerで処理することをおすすめします。

状況によっては、変更がなくてもイベントが発生する場合があります。

内部Hashの変更など、状況によっては変更がなくてもイベントが発生する場合があります。

Callback Urlの動作は、デリバリートラッカーサーバー以外の他のサーバーからCallback Urlにデータを操作して送信できることを前提に設計する必要があります。

Callback Url の情報さえ知っていれば誰でも呼び出すことができるため、デリバリートラッカーサーバーから送られたデータであることを信頼することができません。

注意事項

HMACなどの認証をご希望の場合は別途お問い合わせください。

Callback開発時、配信トラッカーのWebhookサーバーのIPアドレスのみを許可するような措置を取らないでください。

配信トラッカーでCallback Url呼び出しに使用されるIP Addressは、いつでも変更することができます。