Webhook
生成要求に通知先を指定すると、ジョブが成功・失敗・取消で終了したときに Orchestor がその URL へ POST します。受信したバイト列の署名を検証し、保存してから成功応答を返してください。
通知先を指定する
mode: "webhook" と webhook_url を生成要求に含めます。通知先は公開 HTTPS URL が必要です。localhost、プライベートネットワーク、平文 HTTP は指定できません。
export IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST https://api.orchestor.io/v1/creative/video-router/generate \
-H "Authorization: Bearer $ORCHESTOR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d '{
"model": "seedance-2.5",
"prompt": "雨上がりの歩道に映る街灯、水面に広がる小さな波紋",
"duration": 5,
"mode": "webhook",
"webhook_url": "https://example.com/hooks/creative"
}'通知先は自分が管理する受信 URL に置き換えます。ジョブ ID も保存し、通知が届かないときは状態を確認できるようにします。
ペイロードの形式
通知には共通の形式を使い、成功した成果物は payload.artifacts に含まれます。以下は応答の例です。
{
"event": "job.completed",
"request_id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"job_id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"status": "OK",
"payload": {
"artifacts": [
{
"id": "artf_6f1d0c2b9a8e4f7d",
"type": "image",
"url": "https://media.orchestor.io/artifacts/artf_6f1d0c2b9a8e4f7d/output.png",
"content_type": "image/png"
}
]
},
"error": null
}音声も artifacts に含まれます。失敗・取消では payload が null になり、error に理由と次の操作が入ります。通知の OK・ERROR と状態取得の値は区別してください。長期保管する成果物は自分のストレージへ保存します。
署名を検証する
| ヘッダー | 用途 |
|---|---|
x-orchestor-webhook-timestamp | Unix 時刻(秒)。現在時刻との差が300秒以内か検証します。 |
x-orchestor-webhook-signature | orchestor-v1= に続く HMAC-SHA256 の16進数。複数署名はカンマ区切り。 |
x-orchestor-webhook-secret-fingerprint | 署名シークレットの世代を見分ける指紋。秘密値ではありません。 |
署名シークレットを取得する
GET /v1/creative/webhooks/signing-secret でワークスペースの署名シークレットを取得し、サーバー側で保管します。秘密値をブラウザやログに出さないでください。
署名をコードで検証する
署名対象は <timestamp>.<raw body> です。JSON をパースして再び文字列化するとバイト列が変わるため、受信したままの本文を使います。
import hashlib
import hmac
import math
import time
def verify_creative_webhook(raw_body, headers, secret):
# headers は小文字のヘッダー名、raw_body は JSON パース前の bytes。
timestamp = headers.get("x-orchestor-webhook-timestamp", "")
try:
signed_at = float(timestamp)
except (ValueError, TypeError):
return False
if not math.isfinite(signed_at) or abs(time.time() - signed_at) > 300:
return False
digest = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body,
hashlib.sha256).hexdigest()
expected = ("orchestor-v1=" + digest).encode()
return any(hmac.compare_digest(expected, value.strip().encode())
for value in headers.get("x-orchestor-webhook-signature", "").split(","))検証に失敗した通知は処理しません。成功した場合だけ JSON を読み、job_id で重複を判定して保存します。受信時に呼び出された URL の情報も使い、意図したワークスペースのシークレットで検証してください。
手動検証の手順
x-orchestor-webhook-timestampが現在時刻から 300 秒以内であることを確認します。<timestamp>.<raw body>を組み立てます。- 署名シークレットをキーとして HMAC-SHA256 を計算し、16 進数にします。
orchestor-v1=を先頭に付け、カンマ区切りの署名と定時間で比較します。- いずれかの署名が一致した場合だけ本文を処理します。
シークレットをローテーションする
POST /v1/creative/webhooks/signing-secret/rotate は新しい世代と rotation を返します。旧世代の previous_valid_until を確認し、有効期間中は複数の orchestor-v1= エントリのいずれかが一致すれば受け付けます。新しい世代を受信側へ反映してから、期限を過ぎた旧シークレットを外してください。
配信と再試行
| 条件 | 動作 |
|---|---|
10秒以内に 2xx | 配信成功。保存後にすぐ応答し、時間のかかる処理は別に実行します。 |
非 2xx または通信障害 | 合計10回まで試行。最初の再試行は30秒後、以降は倍増して最大1時間間隔。 |
| 試行回数を使い切った | 配信が失敗します。生成ジョブの成功・失敗は変わりません。 |
| 同じ通知が複数回届いた | job_id を使って保存と後続処理を重複させず、受領済みの通知にも 2xx を返します。 |
ジョブの webhook_delivery は試行回数、直近の応答、次回の予定を保持します。GET /v1/creative/jobs/{id}/events でも webhook.delivery を確認できます。
受信先の停止に備えて、低頻度のポーリングも用意してください。