Webhook

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

2026.07.04・読了約7分

同じ追跡番号を何度も取得してポーリングするのは非効率です。荷物追跡APIのWebhookを使えば、配送状況が変わったときだけ通知を受け取れます。この記事では、そのWebhookの使い方を解説します。

Webhookの流れ

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

通知を受け取るエンドポイント（URL）を登録する
追跡番号を登録する（recurring: true で購読）
配送状況が変わると、登録したURLに通知が届く

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で届きます。

{
  "event": "tracking.updated",
  "courierCode": "yamato",
  "trackingNumber": "追跡番号",
  "deliveryStatus": "DELIVERED",
  "deliveryStatusText": "配達完了"
}

署名を検証する

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