Core concepts

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-timestampUnix 時刻(秒)。現在時刻との差が300秒以内か検証します。
x-orchestor-webhook-signatureorchestor-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 の情報も使い、意図したワークスペースのシークレットで検証してください。

手動検証の手順

  1. x-orchestor-webhook-timestamp が現在時刻から 300 秒以内であることを確認します。
  2. <timestamp>.<raw body> を組み立てます。
  3. 署名シークレットをキーとして HMAC-SHA256 を計算し、16 進数にします。
  4. orchestor-v1= を先頭に付け、カンマ区切りの署名と定時間で比較します。
  5. いずれかの署名が一致した場合だけ本文を処理します。

シークレットをローテーションする

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 を確認できます。

受信先の停止に備えて、低頻度のポーリングも用意してください。

関連ページ