Webhook

Settings → Developers → Webhooks（設定 → 開発者 → Webhook）でエンドポイントを追加します（オーナーと管理者）。公開されている HTTPS アドレスである必要があります。受け取るイベントを選びます。All events をオンのままにする（今後 Pellio に追加されるイベントも含みます）か、オフにして必要なイベントを選びます。エンドポイントの署名シークレットは一度だけ表示されます。

各エンドポイントには、受け取るイベントと次の操作が表示されます。

• Edit events：受け取るイベントを変更します。Save events で変更がすぐに適用されます。
• Send test：受け取るイベントに関係なく、そのエンドポイントに webhook.test イベントを送信します。
• Deliveries：直近50回の送信（保留中、配信済み、失敗）とそのレスポンスを表示します。
• Rotate secret：署名シークレットを新しくします。新しいシークレットは一度だけ表示され、古いものはすぐに使えなくなるため、エンドポイントをすぐに更新してください。
• Remove：エンドポイントへの送信を停止します。

API の場合：POST /v1/webhooks は url と events（空のリストはすべてのイベント）を受け取り、PATCH /v1/webhooks/{id} は events を変更し、POST /v1/webhooks/{id}/rotate-secret は新しい secret を返します。

イベント

リクエストボディはすべて { "id", "event", "createdAt", "data" } です。

イベント	タイミング	data
video.created	アップロード、録画、URL からのインポートで動画が作成されたとき。	id、title
video.ready	動画の処理が終わったとき（差し替えやトリミングの後も含む）。	id、title、status、version、durationSeconds、width、height、errorMessage
video.failed	新しい動画を処理できなかったとき。	video.ready と同じ
video.deleted	動画がゴミ箱に移動されたとき（trashed: true）、または完全に削除されたとき。	id、title、trashed
video.watched	識別済みの視聴者（メールフォーム、?email= リンク、または WordPress サイトから）が動画の再生を開始したとき、25％、50％、75％を超えたとき、視聴を完了したとき（訪問をまたいで90％視聴）。視聴者、動画、マイルストーンごとに1回。	video（id、title）、viewer（email、name）、progress（0、25、50、75、100）、milestone（started、25%、50%、75%、completed）、completed
lead.captured	誰かがメールフォームを送信したとき。	id、email、name、fields、video（id、title）、createdAt

配信

Pellio は User-Agent: Pellio-Webhooks/1 ヘッダー付きで POST を送信し、最大10秒待ちます。2xx のレスポンスはすべて配信成功とみなします。リダイレクトはたどらないため、3xx は失敗になります。失敗した配信は合計6回試行され、最初の再試行までは20秒待ち、その後は待ち時間を倍にして最大320秒まで延ばします。

署名の検証

各リクエストには Pellio-Signature ヘッダーが付きます。形式は t=<unix time>,v1=<hex HMAC-SHA256 of "t.body"> で、エンドポイントのシークレットを使います。生のリクエストボディに対して検証してください。

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(header, rawBody, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // 5-minute tolerance
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}