whereparcel

何か聞きたいことがあれば、気軽にどうぞ。WhereParcelを作った開発者が直接メッセージを読んで返信します。

ガイド 10 分で読めます

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

WhereParcelを活用した荷物追跡の自動通知のための信頼性の高いWebhookエンドポイントの設定方法を学びましょう。

WhereParcel Team

Webhookを使用すると、ポーリングなしで荷物のステータス更新を受け取れます。荷物を登録すると、WhereParcelが配達完了まで(最大10日間)約12時間ごとに再確認し、確認のたびに最新のステータスをエンドポイントへ送信します。

なぜWebhookを使うのか?

  • 自動更新 - 登録した荷物を約12時間ごとに再確認してお送りします
  • API呼び出しの削減 - カウントは登録時の1回のみで、その後の確認は無料です
  • ユーザー体験の向上 - ステータスの変化をお客様に自動で伝えられます
  • コスト効率 - 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ドキュメントをご覧ください。

ご希望の配送業者が見つかりませんか?リクエストいただければ迅速に対応いたします。

配送業者をリクエスト →

何か聞きたいことがあれば、気軽にどうぞ。 Discordに来てください — WhereParcelを作った開発者が直接メッセージを読んで返信します。ボットもチケットもなし。気軽に話しかけてください。

Discordに参加 → Slackに参加 →

タグ: #webhooks #best-practices #notifications