AiVideoEditor
無料で始める
メニュー

確認日2026-11-11 · API版2026-11-09 · Markdownを読む

カスタマーウェブフック

ワークスペース向けの送信イベント配信です。HTTPS エンドポイントを登録し、 ワンタイムの署名シークレットを検証し、署名されたイベントを上限付きのリトライで受信します。

エンドポイントの登録

curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  $BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
  • 署名シークレット (whsec_…) は 一度だけ、最初の成功した作成レスポンスで返されます。必ず保管してください。同じ作成の冪等な再生では シークレットなしのエンドポイントが返され、再表示はできません。
  • 宛先は HTTPS で、公開的に解決可能で、埋め込み資格情報を含まないものである必要があります。プライベート、ループバック、リンクローカル (クラウド メタデータを含む)、ユニークローカル、マルチキャストのアドレスへのリクエストは、 接続が確立される前に拒否され、リダイレクトは決して追跡されません。
  • 登録すると、その eventTypes フィルターとは無関係に、そのエンドポイント向けの ターゲット指定された webhook.verification イベントが キューに入ります。通常のイベントは、エンドポイントが検証に 2xx で応答した後にのみ流れます。

配信の検証

すべてのリクエストには次が含まれます:

ヘッダー意味
x-publisher-event-id安定したイベント ID。リトライや再生の間で同一
x-publisher-event-typeイベントタイプ。例: post.published
x-publisher-timestampUnix 秒
x-publisher-signaturet=<ts>,v1=<hex>

署名は、署名シークレットを使用した ${t}.${event_id}.${raw_body} に対する HMAC-SHA256 です。 ±300 秒の許容範囲で検証し、その範囲外の再生は拒否してください。Node の例:

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

function verify(secret, headers, rawBody) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
  if (!m) return false;
  const [t, v1] = [Number(m[1]), m[2]];
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

解析する前に、必ず 生の リクエストボディに対して検証してください。

イベントエンベロープ

{
  "id": "0192d0d0-0000-7000-8000-00000000000f",
  "type": "post.published",
  "createdAt": "2026-11-09T12:00:01Z",
  "apiVersion": "2026-11-09",
  "data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}

初期のイベントカタログ (拡張可能。eventTypes は登録時にフィルター):

  • webhook.verification: チャレンジペイロード。2xx で応答してエンドポイントを有効化
  • post.published: 1 つの宛先がネイティブのレシートとともに確定
  • delivery.failed: 1 つの宛先が最終的に失敗
  • delivery.requires_action: 同意/再接続/遅延レビューが必要

集約された投稿の結果 (post.partially_published、post.failed) はまだ 発行されません。プロデューサーが存在するようになってからここに記載されるため、これらに 依存しないでください。上記の宛先ごとのイベントを購読し、投稿の配信結果からバッチの 状態を導出してください。

リトライ、再生、無効化

  • 試行: 直後、その後 +1m、+5m、+30m、+2h、+8h。リトライは 同じ イベント ID とバイト単位で同一のボディ を再利用するため、安全に重複排除できます。
  • 2xx = 配信済み。429/5xx/タイムアウトはリトライします。その他の 4xx はそのイベントに対して 永久に失敗します (エンドポイントを修正してから再生してください)。
  • 410 Gone はエンドポイントを無効化します。それ以降のイベントはキューに入りません。
  • オペレーターが許可した内部ウェブフックサービス経由の再生は、元の ID のままイベントを再送します。アクティブにリースされている処理中の試行は決して奪われません。再生 はイベントがビジーであることを報告し、しばらくしてから再試行できます。

運用上の注意

  • 配信の診断には安全な結果コードのみが保存されます。シークレット、 署名、リクエストヘッダー、レスポンスボディは決して保存されません。ペイロードはさらに サニタイズされます。プロバイダー/OAuth のシークレットとメディアの presign URL は、 何かがキューに入る前に取り除かれます。
  • エンドポイントはワークスペース単位です。他のワークスペースの エンドポイント UUID を持っていても何も起こりません。
  • 配信は、受け付けたイベントの発生ごとに at-least-once です。x-publisher-event-id で 重複排除してください。

開発者ツールの利用可否

Developers ページは、署名シークレットの暗号化設定とは独立して、ワークスペースの API キーとウェブフックエンドポイントを一覧表示します。ウェブフックの作成には有効な サーバー暗号化設定が必要です。設定の警告の解決はデプロイメントのオペレーターに依頼してください。API キーの 管理は引き続き利用できます。既存の署名シークレットが再表示されることは決してありません。