ビデオ運用のWebhook
自分が利用枠を負担する番組の失敗・紐づけと、残り利用枠を通知できます。メール通知は提供していません。
PUT /api/v1/video-webhook(JSON:{"url":"https://example.com/hook"}) で通知先を登録します。利用者ごとに1か所、登録操作は1時間5回までです。トークンにはupdate権限が必要です。公開IPv4アドレスに解決できるHTTPS・ポート443に限り、内部IP、認証情報入りURL、リダイレクトは許可しません。- 返された
data.signing_secretを安全に保存します。通常の照会では再表示しません。再登録は以前の設定・配信待ちの通知を置き換え、署名キーも更新します。 - 登録先へ
webhook.verificationをPOSTします。受信したdata.challengeと同じ値を{"challenge":"受信した値"}というJSONで2xx応答すると有効になります。GET /api/v1/video-webhook→data.activeで確認できます。確認前には番組情報を送りません。 video_stock.failed、video_stock.matched、video_quota.lowを受信します。利用枠は5分ごとに確認し、使用率90％以上になったときに通知します。同じ低残量状態では繰り返さず、一度90％未満に戻ってから再度到達すると通知します。通知タイミングはキューの処理状況にも依存します。
POSTのJSONは id（イベントID）、type、createdAt（UTCの日時）、data を含みます。ストック通知の data は id、podcastId、clientKey、status、matchedEpisodeId、利用枠通知は usedSeconds、availableSeconds、remainingSeconds です。失敗の詳細は所有者向けのストック取得APIで確認してください。
X-LISTEN-Signature は t=<UNIX秒>,v1=<署名> です。署名は HMAC-SHA256(signing_secret, t + "." + 生のリクエスト本文) の16進表記です。JSONを再生成せず受信した本文を使って検証し、時刻にも許容幅（例：5分）を設けてください。確認通知も同じ方式で署名します。
受信側は保存後に2xxを返し、イベントIDで重複を除外してください。同じイベントは同じIDで再送し、順序は保証しません。失敗時は概ね1分・5分・15分・1時間・3時間後に再送し、最大6試行で終了します。GET /api/v1/video-webhook/deliveries で直近50件の状態・試行回数を確認できます（完了・失敗等の記録は30日間）。送信先の削除は DELETE /api/v1/video-webhook（delete 権限）を使います。すでに送信中のリクエストは取り消せない場合があります。
RESTのレスポンス
ベースURLは https://listen.style です。登録・取得・履歴・削除の成功時は 200 を返します。登録の data には endpoint と signing_secret を含みます。単一取得の data は設定情報（未登録は null）です。設定情報は id・url・active・verified_at で、署名キーは取得できません。
履歴の data[] には id・event_type・status・attempts・created_at・delivered_at を含みます。取得・履歴には read 権限が必要です。削除は data.deleted: true を返します。URL不備は 422、登録回数制限は 429（Retry-After 付き）です。
既存受信先との互換性のため、通知イベント本文は上記の createdAt・podcastId 等の形式を維持します。RESTの設定・履歴レスポンスの項目名とは異なります。署名は通知の元のバイト列で検証してください。