コールバック

タスク作成時に callback_url（HTTPS 必須）を渡すと、タスクが終了状態に達した後に Beatra から POST で通知が届きます。コールバックとポーリングは排他ではありません。タスクの状態は常に GET /v1/tasks/{task_id} が正です。

受け取る内容

POST {callback_url} が届きます。10 秒以内に 2xx を返すと配信成功とみなされます。

{
  "event_id": "evt_01JX...",
  "event_type": "task.succeeded",
  "event_time": "2026-06-11T10:30:00.123456Z",
  "task": { "task_id": "task_01JX...", "status": "succeeded", "output": { "...": "..." } }
}

task は完全な Task envelope です。

署名付きまたは署名なしの配信を選ぶ

コールバック署名キーは API キーとは完全に独立しています。 Console → Developer → Webhooks または /account/callback-signing-keys エンドポイントで作成、ローテーション、 無効化できます。平文のシークレットは作成またはローテーション時に一度だけ表示されます。

• callback_url だけを渡すと署名なしで配信され、2 つの署名ヘッダーは付きません。
• callback_url と有効な callback_signing_key_id を渡すと署名付きで配信されます。
• 選択したキーを利用できない場合は配信に失敗し、署名なしへ暗黙に切り替わることはありません。

署名付き配信を検証する

X-Signature: t=<unix_ts>,v1=<hex>
v1 = HMAC-SHA256( secret, "<unix_ts>." + raw_body )

import hmac, hashlib, time
 
def verify(signature_header: str, raw_body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    ts, sig = int(parts["t"]), parts["v1"]
    if abs(time.time() - ts) > 300:          # 5 分以上ずれたタイムスタンプは拒否
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

注意：必ず生のリクエストボディのバイト列に対して計算してください。先にパースしてから再シリアライズすると検証に失敗します。

リトライポリシー

配信に失敗（非 2xx またはタイムアウト）すると、以下の間隔でリトライします。配信は合計 6 回（初回 1 + リトライ 5）です：

1 分 → 5 分 → 30 分 → 2 時間 → 12 時間

• リトライ中も X-Event-Id は変わりません。これをキーに重複排除してください
• 配信の失敗はタスク自体には影響しません——タスクはすでに終了状態にあり、いつでもポーリングでフォールバックできます
• 各配信の状態は、envelope の callback フィールド（pending / dispatching / delivered / retrying / failed、attempt_count、last_error）とコンソールのコールバックログで確認できます