Webhookを使用すると、荷物のステータスが変更された際にリアルタイムで通知を受け取ることができます。APIを繰り返しポーリングする代わりに、更新情報が自動的に届くのを待つだけで済みます。

なぜWebhookを使うのか？

  • リアルタイム更新 - 荷物のステータスが変わった瞬間に把握できます
  • API呼び出しの削減 - 数分ごとにポーリングする必要がなくなります
  • ユーザー体験の向上 - お客様に即座に通知を届けられます
  • コスト効率 - API使用量が減り、コストを抑えられます

Webhookエンドポイントの設定

Webhookエンドポイントには以下の要件があります：

  1. POSTリクエストを受け付けること
  2. 5秒以内に200ステータスコードを返すこと
  3. 重複イベントを適切に処理できること
// Express.js の例
app.post('/webhooks/whereparcel', (req, res) => {
  const { event, data } = req.body;

  // 常に素早くレスポンスを返す
  res.status(200).json({ received: true });

  // イベントを非同期で処理する
  processTrackingEvent(event, data);
});

セキュリティ：Webhook署名の検証

すべてのWebhookリクエストにはX-WhereParcel-Signatureヘッダーが含まれています。リクエストがWhereParcelから送信されたものであることを確認するために、必ずこの署名を検証してください：

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

失敗時の処理

Webhookの送信は1回のみで、自動再試行はありません。

エンドポイントが10秒以内に2xxを返さない場合、またはDNS・TLS・接続エラーで 到達できない場合、その送信は破棄され、再送されません。

そのためエンドポイントの可用性確保が重要です。次の点が役立ちます：

  • まず2xxを返し、処理はバックグラウンドで行う。 レスポンスの前に時間のかかる 処理（DB書き込み、外部API呼び出し）を行わないでください。
  • Webhook URLの前に認証を置かない。 リクエストには検証用の X-WhereParcel-Signature ヘッダーが付きますがトークンは付きません — 認証の 背後にあるエンドポイントはすべての送信を401で拒否してしまいます。
  • URLを生かしておく。 ホストを停止したりドメインが失効すると、送信は 静かに失敗します。
  • APIで突き合わせる。 取りこぼしが許されない場合は GET /v2/webhooks/subscriptions/{requestId} で現在の状態を確認するほうが Webhookだけに頼るより安全です。

ベストプラクティスまとめ

  1. 素早くレスポンスを返す - 10秒以内に2xxを返すこと
  2. 非同期で処理する - レスポンスをブロックしないこと
  3. 署名を検証する - 常にX-WhereParcel-Signatureを確認すること
  4. 重複を適切に処理する - 冪等性キーを使用すること
  5. エンドポイントを監視する - 再試行がないためダウンタイムは通知の損失に直結します

詳細については、APIドキュメントをご覧ください。