Webhook

荷物追跡APIのWebhookで配送状況の変化を受け取る

2026.07.04・読了約7分

同じ追跡番号を何度も取得してポーリングするのは非効率です。荷物追跡APIのWebhookを使えば、自分でポーリングを実装しなくても最新の配送状況を受け取れます。この記事では、そのWebhookの使い方を解説します。

Webhookの流れ

荷物追跡APIのWebhookは、次の流れで使います。

通知を受け取るエンドポイント（URL）を登録する
追跡番号を登録する（recurring: true で購読）
1時間ごとの巡回のたびに、登録したURLに通知が届く（hasChanged で変化の有無を判定）

1. エンドポイントを登録する

POST /v1/webhooks/endpoints に、通知を受け取るHTTPS URLを登録します。登録時に検証用のテスト通知が送られるため、URLはHTTP 200を返す必要があります。発行された endpointId を次のステップで使います。

2. 追跡番号を登録する

POST /v1/webhooks/register で追跡番号を登録します。recurring を true にすると、14日間の購読になります。

curl https://api.trackingapi.jp/v1/webhooks/register \
  -H "Authorization: Bearer pk_***:sk_***" \
  -H "Content-Type: application/json" \
  -d '{
    "endpointId": "ep_...",
    "items": [{ "courierCode": "yamato", "trackingNumber": "追跡番号" }],
    "recurring": true
  }'

3. 通知を受け取る

巡回のたびに、登録したURLに次のようなペイロードがPOSTで届きます（変化がなくても送信されるため、items[].hasChanged を見て処理を分岐させてください）。

{
  "event": "tracking.polled",
  "requestId": "req_...",
  "timestamp": "2026-01-13T10:30:00.000Z",
  "summary": { "total": 1, "delivered": 1, "active": 0, "hasChanges": true },
  "items": [
    {
      "courierCode": "yamato",
      "trackingNumber": "追跡番号",
      "previousStatus": "IN_TRANSIT",
      "currentStatus": "DELIVERED",
      "hasChanged": true,
      "isDelivered": true,
      "trackingData": { "deliveryStatusText": "配達完了", "...": "..." }
    }
  ]
}

署名を検証する

Webhookのリクエストには署名ヘッダーが付きます。エンドポイント登録時に発行される webhookSecret を使って署名を検証することで、通知が荷物追跡APIから送られたものであることを確認できます。シークレットは POST /v1/webhooks/endpoints/:id/rotate で再発行できます。