荷物追跡のためのWebhookベストプラクティス
WhereParcelを活用した荷物追跡の自動通知のための信頼性の高いWebhookエンドポイントの設定方法を学びましょう。
WhereParcel Team
Webhookを使用すると、ポーリングなしで荷物のステータス更新を受け取れます。荷物を登録すると、WhereParcelが配達完了まで(最大10日間)約12時間ごとに再確認し、確認のたびに最新のステータスをエンドポイントへ送信します。
なぜWebhookを使うのか?
- 自動更新 - 登録した荷物を約12時間ごとに再確認してお送りします
- API呼び出しの削減 - カウントは登録時の1回のみで、その後の確認は無料です
- ユーザー体験の向上 - ステータスの変化をお客様に自動で伝えられます
- コスト効率 - API使用量が減り、コストを抑えられます
Webhookエンドポイントの設定
Webhookエンドポイントには以下の要件があります:
POSTリクエストを受け付けること- 5秒以内に
200ステータスコードを返すこと - 重複イベントを適切に処理できること
// 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だけに頼るより安全です。
ベストプラクティスまとめ
- 素早くレスポンスを返す - 10秒以内に2xxを返すこと
- 非同期で処理する - レスポンスをブロックしないこと
- 署名を検証する - 常に
X-WhereParcel-Signatureを確認すること - 重複を適切に処理する - 冪等性キーを使用すること
- エンドポイントを監視する - 再試行がないためダウンタイムは通知の損失に直結します
詳細については、APIドキュメントをご覧ください。
ご希望の配送業者が見つかりませんか?リクエストいただければ迅速に対応いたします。
配送業者をリクエスト →もっと見る
何か聞きたいことがあれば、気軽にどうぞ。 Discordに来てください — WhereParcelを作った開発者が直接メッセージを読んで返信します。ボットもチケットもなし。気軽に話しかけてください。
Discordに参加 → Slackに参加 →