確認日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-timestamp | Unix 秒 |
x-publisher-signature | t=<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 キーの 管理は引き続き利用できます。既存の署名シークレットが再表示されることは決してありません。