Lymo は Svix 経由で Webhook を配信します。各配信には、Svix SDK で検証可能な標準署名ヘッダーが付きます。
登録前に確認: ホスト名の許可リスト
Webhook の配信先は、組織単位のホスト名許可リスト でゲートされています。Svix 側の URL バリデーションに加えた多層防御で、API キーが漏洩した場合に Svix 経由で SSRF の踏み台にされることを防ぐ仕組みです。
新規組織の既定の許可リストは 空 です。つまり、許可リストに配信先ホスト名を追加するまで、POST /v1/webhooks はすべて 422 invalid_webhook_url で失敗します。統合作業を始める前に、Lymo の担当者（CSM・管理者）に organization_settings.webhook_allowed_hostnames への追加を依頼してください。
- スキームは
https:// のみ。
- 完全一致:
webhook.site は webhook.site のみを許可します。
- サブドメインのワイルドカード:
*.example.com は a.example.com・foo.bar.example.com を許可しますが、apex の example.com 自体は許可しません。
- 大文字小文字は区別せず、punycode 形式で比較されます。
エンドポイントを登録する
curl -X POST "$LYMO_BASE/v1/webhooks" \
-H "Authorization: Bearer $LYMO_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.your-app.example.com/lymo",
"events": ["video.analysis.completed"]
}'
secret（whsec_ で始まる）は、作成時に必ず保存してください。署名検証に必須であり、返却は作成時の 1 回のみです。現時点ではシークレットのローテーション用エンドポイントはありません。紛失・漏洩した場合は、エンドポイントを削除して作り直してください。
events を省略（または [] を指定）すると、すべてのイベント種別を購読します。
イベント種別
| イベント | 状態 | トリガー |
|---|
video.ready | 配信中 | 動画の処理が完了し、分析可能になったとき |
video.analysis.completed | 配信中 | POST /analyses ジョブが成功したとき |
video.analysis.failed | 配信中 | POST /analyses ジョブが確定的に失敗したとき |
deal.scoring.completed | 未配信（配信予定） | POST /scorings ジョブが成功したとき |
deal.scoring.failed | 未配信（配信予定） | POST /scorings ジョブが確定的に失敗したとき |
deal.scoring.* は、SDK の型を安定させる目的でスキーマには定義されていますが、配信側の実装はまだ入っていないため、現時点で購読しても通知は届きません。将来のリリースで有効化予定です。
各イベントのペイロードスキーマは APIリファレンス タブに記載があります。
署名検証
すべての配信には以下のヘッダーが付きます。
svix-id — 配信ごとに一意な ID。再送でも変わりません。svix-timestamp — 送信時の Unix 秒。svix-signature — HMAC 署名。シークレットのローテーション中はスペース区切りで複数の署名が送られ、いずれか一致すれば検証成功となります（切り替え時の検証窓口確保のため）。
各言語の Svix SDK で検証してください。
import { Webhook } from "svix";
const wh = new Webhook(process.env.LYMO_WEBHOOK_SECRET!);
const payload = wh.verify(rawBody, {
"svix-id": req.headers["svix-id"] as string,
"svix-timestamp": req.headers["svix-timestamp"] as string,
"svix-signature": req.headers["svix-signature"] as string,
});
verify には 生のリクエストボディ を渡す必要があります。一度パースして再シリアライズした JSON では検証できません。
配信セマンティクス
- 受信の応答は任意の
2xx ステータスで構いません。非 2xx やネットワーク失敗は指数バックオフで再試行されます。
svix-id は再送間で安定するため、受信済み ID を保存して重複処理をスキップすれば、ハンドラを冪等にできます。- 再試行スケジュール、タイムアウト、保持期間は Svix 側で管理されます。詳細は Svix の配信ドキュメント を参照してください。
一覧取得と削除
# 登録済みエンドポイントの一覧
curl "$LYMO_BASE/v1/webhooks" -H "Authorization: Bearer $LYMO_KEY"
# エンドポイントの削除
curl -X DELETE "$LYMO_BASE/v1/webhooks/ep_2abcXYZ12345" \
-H "Authorization: Bearer $LYMO_KEY"
ep_ で始まります。削除は即時反映されます。配信中のイベントは完了しますが、以降の新規イベントは送られません。