荷物追跡のためのWebhookベストプラクティス

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-Webhook-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)
  );
}

失敗時の処理

エンドポイントが利用できない場合、WhereParcelは指数バックオフで再試行を行います：

試行遅延時間
1回目の再試行1分
2回目の再試行5分
3回目の再試行30分
4回目の再試行2時間
5回目の再試行12時間

5回の再試行がすべて失敗した場合、Webhookは失敗としてマークされ、メールで通知が届きます。

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

  1. 素早くレスポンスを返す - 5秒以内に200を返すこと
  2. 非同期で処理する - レスポンスをブロックしないこと
  3. 署名を検証する - 常にX-Webhook-Signatureを確認すること
  4. 重複を適切に処理する - 冪等性キーを使用すること
  5. エンドポイントを監視する - 障害時のアラートを設定すること

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