Webhooks: HMAC署名、再配信、ベストプラクティス
Webhookで文字起こし結果を受け取る方法: HMAC-SHA256署名、X-VPT-SignatureヘッダーとX-VPT-Eventヘッダー、バックオフ付き再配信6回。
文字起こしが完了したかどうかをAPIへ問い合わせ続ける代わりに、リクエストでwebhook_urlを指定すると、VoxScriberはジョブが完了したときに（成功でもエラーでも）あなたのサーバーへPOSTを送信します。これは推奨される連携方法です：APIリクエストの消費が少なく、結果がすぐに届きます。
仕組み
webhook_url（必須でhttps）を指定して音声を送信します。- 処理が完了すると、結果を添えてこのURLへPOSTを送信します。
- サーバーが受信を確認するために
2xxステータスで応答します。
各配信には2つの識別ヘッダーが含まれます：
| ヘッダー | 内容 |
|---|---|
X-VPT-Event | イベントの種類（完了、失敗など） |
X-VPT-Signature | 配信のHMAC-SHA256署名 |
署名を確認せずにコンテンツを信頼しないでください：受信した本文のHMAC-SHA256を計算し、X-VPT-Signatureヘッダーの値と比較します。有効な署名がないリクエストは破棄してください。誰でもあなたのエンドポイントURLを知り得るためです。
自動再配信
エンドポイントがダウンしているか、応答が遅すぎる場合、再試行します。
- 試行ごとのタイムアウト: 15秒。
- 最大試行回数: 6回。
- 試行間の待機時間（バックオフ）: 5分 → 30分 → 2時間 → 6時間 → 24時間。
すべての配信は当社側に永続化されるため、何かが失われた場合はサポートと履歴を監査できます。
Webhookにはすぐに200で応答し、コンテンツを非同期（キュー、ジョブ）で処理してください。処理に15秒以上かかると、配信は失敗と見なされて再配信キューに入ります。同じイベントを2回受信する可能性があるため、イベントは冪等に処理してください。
最終結果は必ず届きます
スタックしたジョブも黙って消えません：
- キュー内で10分以上停止したジョブは自動的に再キューイングされます。
- 処理中で60分以上スタックしたジョブは失敗とマークされ、あなたのURLへエラーwebhookが送信されます。
つまり、送信された各音声について、成功または失敗の最終コールバックがあなたのシステムに届きます。
FAQ
サーバーがダウンしていました。結果は失われますか？
おそらく失われません。約24時間にわたって最大6回試行されます。すべて失敗した場合も配信履歴は記録されているので、再処理についてサポートにご連絡ください。
http（TLSなし）のURLを使えますか？
いいえ。セキュリティのため、httpsURLのみ受け付けています。リダイレクトはなく、内部/プライベートアドレスはブロックされます。
成功のwebhookとエラーのwebhookはどう見分けますか？
X-VPT-Eventヘッダーがイベントの種類を識別し、配信本文の内容でも判断できます。
エンドポイントは何を返す必要がありますか？
15秒以内の任意の2xxステータスです。それ以外のステータス（またはタイムアウト）は失敗と見なされ、再配信が行われます。
関連記事
解決しない場合は チケットを開く — チームが迅速に対応します。