Webhook
terminal event を購読し、Standard Webhooks 署名を検証し、delivery history を確認します。
このガイドでは、webhook endpoint を作成し、delivery の署名を検証し、過去の event を確認または再送する方法を説明します。
Webhook は public HTTPS endpoint に event notification を送ります。endpoint と delivery operation は MANAGE_WEBHOOKS で管理します。
Event vocabulary
閉じた event set は次の 5 つです。
| event | 意味 |
|---|---|
video.indexed | 動画が index 完了 state になりました。 |
video.failed | 動画の processing に失敗しました。 |
run.completed | ワークフローまたは analysis run が完了しました。 |
run.failed | run に失敗しました。 |
run.canceled | run が cancel されました。 |
すべての event は同じ envelope を使います。
{
"id": "evt_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
"type": "run.completed",
"created_at": "2026-08-08T10:05:00.000Z",
"data": {
"run_id": "run_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
"status": "completed"
}
}event 固有の data object も snake_case を使います。正しい result は GET /api/v1alpha1/runs/{run_id} で確認してください。
Endpoint を作成する
curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/webhooks" \
-H "Authorization: Bearer $DEEPFRAME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: webhook-create-01" \
-d '{
"url": "https://hooks.example.com/deepframe",
"description": "Review event receiver",
"events": ["video.indexed", "run.completed"]
}'create response は endpoint id と signing secret を 1 回だけ返します。安全に保存してください。list、get、update response に secret は含まれません。endpoint URL は public HTTPS で、API の SSRF policy を通過する必要があります。
新しく作成した webhook は既定で有効です。enabled は create では受け付けられませんが response には含まれ、後から PATCH /api/v1alpha1/webhooks/{webhook_id} で切り替えられます。
Delivery を検証する
Standard Webhooks delivery は endpoint secret と次の header を使います。
webhook-idwebhook-timestampwebhook-signature
raw request body、timestamp tolerance、signature を JSON parse 前に検証してください。古い timestamp と replay された event id は receiver policy に従って拒否してください。
Delivery history と redelivery
delivery history を一覧取得します。
curl --fail-with-body "$BASE_URL/api/v1alpha1/webhooks/$WEBHOOK_ID/deliveries" \
-H "Authorization: Bearer $DEEPFRAME_API_KEY"POST /api/v1alpha1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver と Idempotency-Key で redelivery を要求します。redelivery は非同期なので、delivery record の status と attempt 数を確認してください。