Webhook
自分が利用枠を負担する番組の失敗・紐づけと、残り利用枠を通知できます。メール通知は提供していません。
RSS取り込みと文字起こしの完了も、イベントを指定して通知できます。既存URLとの互換性のため、設定先は引き続き /api/v1/video-webhook です。無料を含む全プランで利用できます。
RSS取り込み・文字起こし完了
{"url":"https://example.com/hook","events":["episode.imported","transcript.completed"]}
上記を PUT /api/v1/video-webhook に送信します。
episode.imported: RSSから新しいエピソードが登録されたとき。既存エピソードの再取得・内容更新では通知しません。メディア変換や文字起こしの完了を意味しません。transcript.completed: LISTENの自動文字起こし結果が保存されたとき、またはWeb/APIからの字幕アップロードが完了したとき。同じエピソード・同じソース・同じ内容は重複通知しません。自動話者分離・要約・校正候補生成は別処理で、完了を待ちません。字幕エディタでの修正やRSS側の字幕取得は対象外です。
events を省略すると従来のビデオ3種類のみです。既存の受信先にも新イベントを自動追加しません。選択したイベントだけ届くため、ビデオ通知も必要なら video_stock.failed・video_stock.matched・video_quota.low を含めてください。再登録すると署名キーが変わり、再度の確認応答が必要です。
対象は、利用枠を負担するユーザー自身がオーナー権限を持つ番組です。未確認の送信先には通知しません。送信前に権限を失った場合やエピソードが削除された場合は取り消します。登録前の過去イベントは遡って通知しません。
{"id":"EVENT_ID","type":"transcript.completed","createdAt":"2026-10-15T10:00:00.000000Z","data":{"episodeId":"EPISODE_ID","podcastId":"PODCAST_ID","guid":"RSS_GUID","source":"automatic","revision":"64-character-content-hash"}}
episode.imported の data は episodeId・podcastId・guid、文字起こし完了は加えて source（automatic / upload）と revision を含みます。本文・要約・メディアURLは送りません。設定の取得では選択中の events も返します。通知後はエピソード取得APIなどで最新状態を取得してください。順序は保証されないため、到着順を処理順とみなさないでください。
登録・署名・再送
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の設定・履歴レスポンスの項目名とは異なります。署名は通知の元のバイト列で検証してください。