Webhook

概要

非同期生成タスクを送信すると、Atlas Cloud はバックグラウンドで処理を行い、結果はしばらく経ってから利用可能になります。タスクが完了するまで 予測 エンドポイントを繰り返し呼び出す代わりに、タスクが終了状態に達した瞬間に Atlas Cloud から コールバックしてもらう ことができます。

これはタスクの送信時に webhook_url を指定するだけで有効になります。タスクが完了すると — 成功、失敗、タイムアウト のいずれであっても — Atlas Cloud はその URL に、最終結果を含む署名済みの POST を 1 回だけ送信します。

Webhook はポーリングを 補完 するものであり、置き換えるものではありません。予測 エンドポイントはこれまでとまったく同じように動作し、Webhook のペイロードにはポーリングで取得できるものと同じ形式の結果が含まれます。どちらか一方でも、両方でも利用できます。

クイックスタート

既存の送信リクエストに webhook_url フィールドを追加します:

curl -X POST https://api.atlascloud.ai/api/v1/model/generateVideo \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "bytedance/seedance-2.0/text-to-video",
        "prompt": "A calico kitten chasing a butterfly in a garden, cinematic",
        "duration": 5,
        "resolution": "1080p",
        "webhook_url": "https://your-app.example.com/hooks/atlascloud"
      }'

同じ webhook_url フィールドは、POST /api/v1/model/generateImage（非同期の画像生成、event_type: "image.task.terminal"）と POST /api/v1/model/generateAudio（非同期の音声生成、event_type: "audio.task.terminal"）でもまったく同じように機能します。

送信レスポンスは変わりません — これまでどおり、タスクの id（session_id）がすぐに返されます。webhook_url は Atlas Cloud 内で消費され、上流のモデルプロバイダーに転送されることは決してありません。タスクが完了すると、指定したエンドポイントが POST を受け取ります。

webhook_url の要件

コールバック URL は送信時に検証されます。検証に失敗した場合、送信リクエストは HTTP 400 で拒否され、タスクは作成されません（課金も発生しません）。

コールバックリクエスト

タスクが終了状態に達すると、Atlas Cloud は Content-Type: application/json と以下のヘッダーを付けて POST を送信します:

ペイロード

{
  "session_id": "string",       // タスク ID。冪等性キーとして使います
  "event_type": "string",       // 例: "video.task.terminal"
  "status": "OK" | "ERROR",     // トップレベルの結果 — ここで分岐します
  "created_at": 1782295062952,  // タスク作成時刻（エポックミリ秒）
  "payload": {                  // 結果。Predictions API と同じ形式です
    "model": "string",
    "status": "completed" | "failed" | "timeout",
    "outputs": ["https://..."], // 成功時に存在します
    "error_code": 0             // 失敗時に存在します
  },
  "error": "string"             // status == "ERROR" の場合のみ存在します
}

ハンドラーではトップレベルの status フィールドで分岐してください: OK は payload.outputs に利用可能な結果があることを意味し、ERROR はタスクが結果を生成しなかったことを意味して、error にその理由が示されます。

成功例

完了した bytedance/seedance-2.0/text-to-video タスクの実際の配信例:

{
  "session_id": "6a0c02cdb4b147b7bc78881eb7229ece",
  "event_type": "video.task.terminal",
  "status": "OK",
  "created_at": 1782295062952,
  "payload": {
    "model": "bytedance/seedance-2.0/text-to-video",
    "status": "completed",
    "outputs": [
      "https://atlas-media.oss-us-west-1.aliyuncs.com/videos/cgt-20260624-0.mp4"
    ]
  }
}

失敗例

{
  "session_id": "9b2f4e7a1c0d4f5e8a6b3c2d1e0f9a8b",
  "event_type": "video.task.terminal",
  "status": "ERROR",
  "created_at": 1782200000000,
  "payload": {
    "model": "bytedance/seedance-2.0/text-to-video",
    "status": "failed",
    "error_code": 1039
  },
  "error": "the input was rejected by content moderation"
}

timeout の場合も同じ形式で、payload.status: "timeout" と一般的な error メッセージが返されます。

署名の検証

Ed25519 + JWKS（推奨）

Atlas Cloud は各配信を Ed25519 の秘密鍵で署名し、対応する 公開 鍵を JWKS エンドポイントで公開しています。この公開鍵で検証するため、利用者側でシークレットを用意したりローテーションしたりする必要はありません。

• 公開鍵（JWKS）: GET https://api.atlascloud.ai/api/v1/webhooks/jwks.json（認証不要）:

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "Wn_rgZDBO6nv4-ka97PPf5z8WXbM25o75dR6YukTqqI",
      "use": "sig",
      "alg": "EdDSA",
      "kid": "cnut8IN2blKoB5zRJr9th0HoLzH-iBH3WYoUtkcJZQE"
    }
  ]
}

• 署名対象のメッセージ: "<timestamp>.<raw_body>" — X-AtlasCloud-Webhook-Timestamp の値、リテラルの .、そして リクエストボディの正確な生バイト列 です。HMAC とは異なり、タイムスタンプが署名の対象に 含まれる ため、リプレイウィンドウを適用できます。
• 署名ヘッダー: X-AtlasCloud-Webhook-Signature-Ed25519（base64url）。HMAC が廃止された後、Ed25519 署名は X-AtlasCloud-Webhook-Signature に移ります — したがって -Ed25519 ヘッダーがあればそれを優先し、なければ -Signature にフォールバックしてください。
• 鍵 ID: X-AtlasCloud-Webhook-Key-Id は、その配信に署名した JWK の kid です。

手順

1. X-AtlasCloud-Webhook-Timestamp（ts）、X-AtlasCloud-Webhook-Key-Id（kid）、および Ed25519 署名ヘッダーを読み取ります。
2. （推奨）タイムスタンプが自分の時計から約 5 分以上ずれている場合は拒否します（リプレイ対策）。
3. JWKS を取得し、kid が一致する鍵を選びます。JWKS は キャッシュ し、認識できない kid を受け取った場合は 1 度だけ再取得 してください（署名鍵がローテーションされた可能性があります）。
4. JWK の x（base64url）をデコードして、32 バイトの Ed25519 公開鍵を取得します。
5. ts + "." + raw_body に対して、base64url デコードした署名を検証します。

const crypto = require("crypto");

const JWKS_URL = "https://api.atlascloud.ai/api/v1/webhooks/jwks.json";
let jwks = {}; // kid -> jwk

async function publicKey(kid) {
  if (!jwks[kid]) {
    const { keys } = await (await fetch(JWKS_URL)).json();
    jwks = Object.fromEntries(keys.map((k) => [k.kid, k]));
  }
  const jwk = jwks[kid];
  return jwk && crypto.createPublicKey({ key: jwk, format: "jwk" });
}

// req.body は生のボディ Buffer である必要があります（例: express.raw()）。
async function verifyEd25519(req) {
  const ts = req.get("X-AtlasCloud-Webhook-Timestamp");
  const kid = req.get("X-AtlasCloud-Webhook-Key-Id");
  const sig =
    req.get("X-AtlasCloud-Webhook-Signature-Ed25519") ||
    req.get("X-AtlasCloud-Webhook-Signature");

  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // リプレイウィンドウ

  const pub = await publicKey(kid);
  if (!pub) return false;
  const msg = Buffer.concat([Buffer.from(`${ts}.`), req.body]);
  return crypto.verify(null, msg, pub, Buffer.from(sig, "base64url"));
}

HMAC（レガシー）

署名は次のように計算されます:

HMAC-SHA256( signing_secret, raw_request_body )   →   lowercase hex

• 鍵は 共有の署名シークレット（アカウントごとに発行されます）です。
• メッセージは リクエストボディの正確な生バイト列 です — JSON を再シリアライズするとバイト順や空白が変わる可能性があるため、再シリアライズの 前 に検証してください。
• 計算結果は X-AtlasCloud-Webhook-Signature ヘッダーと 定数時間 で比較してください。

X-AtlasCloud-Webhook-Timestamp ヘッダーは参考情報です（任意のリプレイウィンドウのチェックに利用できます）。署名対象には 含まれません — 署名されるのは生のボディのみです。

const crypto = require("crypto");
const express = require("express");
const app = express();

const SIGNING_SECRET = process.env.ATLASCLOUD_WEBHOOK_SECRET;

// 生のボディを取得します — JSON パーサーを先に実行させないでください。
app.use("/hooks/atlascloud", express.raw({ type: "*/*" }));

app.post("/hooks/atlascloud", (req, res) => {
  const sig = req.get("X-AtlasCloud-Webhook-Signature") || "";
  const expected = crypto
    .createHmac("sha256", SIGNING_SECRET)
    .update(req.body)               // req.body は Buffer（生バイト列）です
    .digest("hex");

  // Buffer として比較し、バイト長でガードします: timingSafeEqual は長さが異なる
  // 入力で例外を投げ、不正なマルチバイトのヘッダーは JS の文字列長では一致しても
  // バイト長では異なることがあります。
  const sigBuf = Buffer.from(sig);
  const expBuf = Buffer.from(expected);
  const ok =
    sigBuf.length === expBuf.length &&
    crypto.timingSafeEqual(sigBuf, expBuf);
  if (!ok) return res.status(401).send("invalid signature");

  const event = JSON.parse(req.body.toString("utf8"));
  // ... event.session_id をキーにキューへ入れ、すばやく応答します ...
  res.status(200).send("ok");
});

配信のセマンティクス

配信の確認応答

受信を確認するには、任意の 2xx ステータスコードを返してください。それ以外のステータスコード、または接続タイムアウトは失敗と見なされ、配信は 再送 されます。

すばやく 応答してください（数秒以内に十分収まるように）。実際の処理は非同期で行います: 署名を検証し、session_id をキーにしてイベントをキューへ入れ、すぐに 200 を返します。応答が遅いとタイムアウトし、不要な再送を招く恐れがあります。

再送とバックオフ

配信が確認応答されない場合、Atlas Cloud は 指数バックオフ（おおよそ 10s → 20s → 40s → …、上限は約 30 分）で最大 約 10 回 まで再送します。試行回数を使い切ると、その配信は配信不能としてマークされ、以降は再送されません。

at-least-once — session_id で重複排除する

session_id は再送をまたいで変わりません。すでに完全に処理済みの session_id に対する Webhook は何もせず、200 を返してください。

適時性

大半の Webhook は、タスク完了から数秒以内に配信されます。組み込みの整合性チェックによるセーフティネットにより、高速パスを取り逃した場合（サービスのデプロイ中など）でも配信は保証されますが、その稀なケースでは最大 30 分程度の遅延が生じます。瞬時かつ exactly-once ではなく、最終的に、at-least-once で配信されるものとして設計してください。

ベストプラクティス

• パブリックに到達可能な ホスト上で、コールバックを HTTPS で受け付ける。
• イベントを信頼する前に Webhook の署名を検証する — できれば Ed25519/JWKS を使う（保管すべきシークレットがなく、kid で取得した公開鍵で検証できます）。HMAC は移行期間中のレガシーなフォールバックです。
• Ed25519 で検証する際は JWKS をキャッシュ し、未知の kid では再取得する。"<timestamp>.<raw_body>" に対して署名を検証し、リプレイウィンドウを適用する。
• 2xx をすばやく返す。実際の処理はバックグラウンドのキューに移す。
• session_id で重複排除する — ハンドラーは冪等でなければなりません。
• トップレベルの status で分岐する（OK と ERROR）。結果は payload.outputs から読み取る。
• 順序や exactly-once を前提にしない。at-least-once を前提に設計する。
• 予測 エンドポイントをフォールバック / 整合性チェックの経路として残しておく。
• レガシーな HMAC を使う場合のみ: 署名シークレットを機密として扱い、漏洩した場合はローテーションする。（Ed25519/JWKS では利用者側にシークレットはありません。）

トラブルシューティング

リファレンス

• 送信（Webhook 付き）: POST /api/v1/model/generateVideo、POST /api/v1/model/generateImage、POST /api/v1/model/generateAudio — webhook_url を追加します。
• イベントタイプ: video.task.terminal、image.task.terminal、audio.task.terminal。
• JWKS（公開鍵）: GET /api/v1/webhooks/jwks.json。
• 署名（Ed25519、推奨）: "<timestamp>.<raw_body>" に対する base64url の Ed25519 署名。X-AtlasCloud-Webhook-Signature-Ed25519 に格納されます（鍵 ID は X-AtlasCloud-Webhook-Key-Id）。
• 署名（HMAC、レガシー）: HMAC-SHA256(signing_secret, raw_body) の 16 進表現。X-AtlasCloud-Webhook-Signature に格納されます。
• 冪等性キー: session_id（X-AtlasCloud-Webhook-Id にも含まれます）。
• ポーリングによる代替手段: 予測。