Webhook

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"

エンドポイント ID は Svix が発行し、ep_ で始まります。削除は即時反映されます。配信中のイベントは完了しますが、以降の新規イベントは送られません。

はじめに

コンセプト

登録前に確認: ホスト名の許可リスト

エンドポイントを登録する

イベント種別

署名検証

配信セマンティクス

一覧取得と削除

​登録前に確認: ホスト名の許可リスト

​エンドポイントを登録する

​イベント種別

​署名検証

​配信セマンティクス

​一覧取得と削除

登録前に確認: ホスト名の許可リスト

エンドポイントを登録する

イベント種別

署名検証

配信セマンティクス

一覧取得と削除