Webhooks

​

概要

• イベント駆動型プッシュ — リソースの状態変化時に能動的に通知し、クライアント側のポーリングは不要
• envelope 構造 — 統一された BetaWebhookEvent { id, created_at, data, type:"event" } フォーマット
• 配信セマンティクス — 少なくとも 1 回(at-least-once)の保証、HMAC-SHA256 署名検証、指数バックオフによるリトライ
• ワイルドカード購読 — * を使用してすべてのイベントタイプを購読でき、連携を簡素化

​

ドメインタイプ

​

Session ライフサイクルイベント

​

Webhook Session Created Event Data

• WebhookSessionCreatedEventData object { id, type }
  • id: string イベントをトリガーした Session ID。
  • type: "session.created"
    • "session.created"
    Session が正常に作成されたときにトリガーされます。システムは POST /sessions により Session が作成された直後にこのイベントを送信します。

​

Webhook Session Updated Event Data

• WebhookSessionUpdatedEventData object { id, type }
  • id: string イベントをトリガーした Session ID。
  • type: "session.updated"
    • "session.updated"
    Session のメタデータ(タイトルや metadata など)が変更されたときにトリガーされます。

​

Webhook Session Archived Event Data

• WebhookSessionArchivedEventData object { id, type }
  • id: string イベントをトリガーした Session ID。
  • type: "session.archived"
    • "session.archived"
    Session がアーカイブされたときにトリガーされます。アーカイブ後、Session は新しいメッセージを受け付けなくなりますが、履歴データは引き続き照会可能です。

​

Webhook Session Deleted Event Data

• WebhookSessionDeletedEventData object { id, type }
  • id: string イベントをトリガーした Session ID。
  • type: "session.deleted"
    • "session.deleted"
    Session が永久に削除されたときにトリガーされます。削除後、Session のすべてのデータは復元できなくなります。

​

Session ステータスイベント

​

Webhook Session Status Run Started Event Data

• WebhookSessionStatusRunStartedEventData object { id, type }
  • id: string イベントをトリガーした Session ID。
  • type: "session.status_run_started"
    • "session.status_run_started"
    Agent が実行を開始したときにトリガーされます。Session が実行状態に入り、ユーザーの指示を実行していることを示します。

​

Webhook Session Status Idled Event Data

• WebhookSessionStatusIdledEventData object { id, type }
  • id: string イベントをトリガーした Session ID。
  • type: "session.status_idled"
    • "session.status_idled"
    ターンが完了し、Session がアイドル状態に戻ったときにトリガーされます。この時点で Session の最新の出力を安全に読み取ることができます。

​

Session Thread イベント

​

Webhook Session Thread Created Event Data

• WebhookSessionThreadCreatedEventData object { id, type, session_thread_id }
  • id: string イベントをトリガーした Session ID。
  • type: "session.thread_created"
    • "session.thread_created"
    新しい Session Thread が作成されたときにトリガーされます。メイン Agent がタスクを実行するために子スレッドを生成する、サブ Agent 協調シナリオでよく見られます。
  • session_thread_id: string 関連付けられた Session Thread ID。

​

Webhook Session Thread Idled Event Data

• WebhookSessionThreadIdledEventData object { id, type, session_thread_id }
  • id: string イベントをトリガーした Session ID。
  • type: "session.thread_idled"
    • "session.thread_idled"
    Session Thread が実行を終了してアイドル状態に入ったときにトリガーされます。スレッドが現在のタスクを完了し、結果を読み取れることを示します。
  • session_thread_id: string 関連付けられた Session Thread ID。

​

Webhook Session Thread Terminated Event Data

• WebhookSessionThreadTerminatedEventData object { id, type, session_thread_id }
  • id: string イベントをトリガーした Session ID。
  • type: "session.thread_terminated"
    • "session.thread_terminated"
    Session Thread が終了(terminate)されたときにトリガーされます。終了された Thread は復元できません。作業を続けるには新しい Thread を作成する必要があります。
  • session_thread_id: string 関連付けられた Session Thread ID。

​

Agent ライフサイクルイベント

​

Webhook Agent Created Event Data

• WebhookAgentCreatedEventData object { id, type, version }
  • id: string イベントをトリガーした Agent ID。
  • type: "agent.created"
    • "agent.created"
    Agent が正常に作成されたときにトリガーされます。システムは POST /agents により Agent が作成された後にこのイベントを送信します。
  • version: integer Agent のバージョン番号。初回作成時は 1 に設定されます。

​

Webhook Agent Updated Event Data

• WebhookAgentUpdatedEventData object { id, type, version }
  • id: string イベントをトリガーした Agent ID。
  • type: "agent.updated"
    • "agent.updated"
    Agent の設定が更新されたときにトリガーされます。version は更新のたびにインクリメントされます。
  • version: integer Agent のバージョン番号。

​

Webhook Agent Archived Event Data

• WebhookAgentArchivedEventData object { id, type, version }
  • id: string イベントをトリガーした Agent ID。
  • type: "agent.archived"
    • "agent.archived"
    Agent がアーカイブされたときにトリガーされます。アーカイブ後、Agent は新しい Session 作成リクエストを受け付けなくなります。
  • version: integer Agent のバージョン番号。

​

Webhook Agent Deleted Event Data

• WebhookAgentDeletedEventData object { id, type, version }
  • id: string イベントをトリガーした Agent ID。
  • type: "agent.deleted"
    • "agent.deleted"
    Agent が削除されたときにトリガーされます。削除後、Agent のすべての設定データは復元できなくなります。
  • version: integer Agent のバージョン番号。

​

Webhook エンドポイント API

Authorization: Bearer $PAT

​

POST /webhook_endpoints

{
  "id": "5fc05310-4d9c-447e-a4b8-f124f17e1ff0",
  "url": "https://webhook.site/your-unique-path",
  "description": "quickstart demo",
  "events": ["*"],
  "active": true,
  "signing_secret": "whsec_BfJDodFEzmkdjAUf19-_XthSq6KbPKmRjfm9KFWMIuk",
  "signing_secret_version": 1,
  "created_at": "2026-07-02T18:17:30.069191+08:00"
}

Note: signing_secret は作成時に一度だけ返されます。安全に保管してください。以降の照会系エンドポイントではこのフィールドは返されません。

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.site/your-unique-path",
    "description": "quickstart demo",
    "events": ["*"]
  }'

​

GET /webhook_endpoints

{
  "data": [
    {
      "id": "700e7789-edab-41cb-b60a-210d0df38ab6",
      "url": "https://myapp.example.com/hooks/qoder",
      "description": "prod app hook",
      "events": ["session.created", "session.thread_idled"],
      "active": true,
      "signing_secret_version": 1,
      "consecutive_fail": 0,
      "last_success_at": "2026-07-02T18:08:12.666783+08:00",
      "created_at": "2026-07-02T17:47:16.073822+08:00",
      "updated_at": "2026-07-02T17:47:16.073822+08:00"
    }
  ]
}

curl https://api.qoder.com/api/v1/cloud/webhook_endpoints \
  -H "Authorization: Bearer $PAT"

​

GET /webhook_endpoints/{id}

curl https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6 \
  -H "Authorization: Bearer $PAT"

​

PUT /webhook_endpoints/{id}

curl -X PUT https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6 \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["session.created", "session.status_idled", "agent.updated"],
    "description": "updated prod hook"
  }'

​

DELETE /webhook_endpoints/{id}

curl -X DELETE https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6 \
  -H "Authorization: Bearer $PAT"

​

POST /webhook_endpoints/{id}/test

{"event_id": 433, "delivery_rows": 2}

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6/test \
  -H "Authorization: Bearer $PAT"

​

POST /webhook_endpoints/{id}/enable

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6/enable \
  -H "Authorization: Bearer $PAT"

​

POST /webhook_endpoints/{id}/disable

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6/disable \
  -H "Authorization: Bearer $PAT"

​

GET /webhook_events

curl https://api.qoder.com/api/v1/cloud/webhook_events \
  -H "Authorization: Bearer $PAT"

​

GET /webhook_events/{id}

curl https://api.qoder.com/api/v1/cloud/webhook_events/433 \
  -H "Authorization: Bearer $PAT"

​

エラーレスポンス形式

{
  "error": {
    "message": "Unknown event type: agent.updated",
    "type": "invalid_request_error"
  },
  "request_id": "cc865161-b25d-4d68-bad5-bf0363f6e0f9",
  "type": "error"
}

注意: 認証層(Token が無効または欠落している場合など)が返す 401 レスポンスは、ゲートウェイから直接返されるため、上記の業務エラー構造に従わない場合があります。

​

Webhook 配信

​

配信方法

• Method: POST
• Content-Type: application/json
• Body: JSON envelope 構造（envelope 構造を参照）

​

リクエストヘッダー

​

署名検証

t=1719907336,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8f9

signature = HMAC_SHA256(signing_secret, "<t>.<raw_body>")

• signing_secret — エンドポイント作成時に返されるシークレット(whsec_ プレフィックス)
• t — 署名時の Unix タイムスタンプ(秒)
• raw_body — リクエストボディの生のバイト内容(パース前)

1. Webhook-Signature ヘッダーから t と v1 を抽出する
2. リプレイ攻撃を防ぐため、タイムスタンプが許容ウィンドウ内(推奨 600 秒)であることを確認する
3. signing_secret を使用して "<t>.<raw_body>" の HMAC-SHA256 を計算する
4. 結果を v1 とタイミングセーフな比較で照合する

​

署名検証のコード例

const crypto = require('node:crypto');

function verifyWebhook(secret, rawBody, header, toleranceSec = 600) {
  const parts = Object.fromEntries(
    header.split(',').map(kv => kv.split('=').map(s => s.trim()))
  );
  const ts = parseInt(parts.t, 10);
  if (Math.abs(Date.now() / 1000 - ts) > toleranceSec) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(parts.v1, 'hex')
  );
}

import hmac, hashlib, time

def verify_webhook(secret: bytes, raw_body: bytes, header: str, tolerance_sec: int = 600) -> bool:
    parts = dict(kv.split("=", 1) for kv in header.split(","))
    ts = int(parts["t"])
    if abs(time.time() - ts) > tolerance_sec:
        return False
    signed_payload = f"{ts}.".encode() + raw_body
    expected = hmac.new(secret, signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

func verifyWebhook(secret, rawBody []byte, header string, toleranceSec int64) bool {
    var ts int64; var v1 string
    for _, kv := range strings.Split(header, ",") {
        kv = strings.TrimSpace(kv)
        if strings.HasPrefix(kv, "t=") { ts, _ = strconv.ParseInt(kv[2:], 10, 64) }
        if strings.HasPrefix(kv, "v1=") { v1 = kv[3:] }
    }
    if ts == 0 || v1 == "" { return false }
    if diff := time.Now().Unix() - ts; diff > toleranceSec || diff < -toleranceSec { return false }
    mac := hmac.New(sha256.New, secret)
    fmt.Fprintf(mac, "%d.", ts)
    mac.Write(rawBody)
    return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(v1))
}

​

リトライ戦略

​

レスポンスコードの処理

​

自動デグレード

• エンドポイント URL が到達可能か
• SSL 証明書が有効か
• サーバーが正常に応答しているか
• 署名検証ロジックにバグがないか

​

サポート対象のイベントタイプ(完全な一覧)

​

イベントタイプ概要

​

特殊なイベントタイプ

​

ステータスラベル

​

envelope 構造

​

基本 envelope 構造

{
  "id": "whevt_a1b2c3d4e5f67890",
  "created_at": "2026-07-02T10:02:16Z",
  "type": "event",
  "data": {
    "id": "sess_019f224773fe71d79c5869bd089d159c",
    "type": "session.created"
  }
}

​

Thread イベントの envelope

{
  "id": "whevt_a1b2c3d4e5f67890",
  "created_at": "2026-07-02T10:02:17Z",
  "type": "event",
  "data": {
    "id": "sess_019f224773fe71d79c5869bd089d159c",
    "type": "session.thread_idled",
    "session_thread_id": "sthread_019f224..."
  }
}

​

Agent イベントの envelope

{
  "id": "whevt_a1b2c3d4e5f67890",
  "created_at": "2026-07-02T10:02:16Z",
  "type": "event",
  "data": {
    "id": "agent_019f224773fe71d7...",
    "type": "agent.created",
    "version": 1
  }
}

​

フィールドの説明

​

冪等性の処理

1. id を重複排除の一意キーとして使用する
2. 処理前に id がすでに消費済みかどうかを確認する
3. イベント処理ロジックが冪等であることを保証する

​

計画中のイベント(近日提供予定)

​

deployment.*(Deployment ライフサイクル、6 イベント)

​

deployment_run.*(Deployment 実行ステータス、3 イベント)

​

environment.*(Environment 管理、4 イベント)

​

memory_store.*(Memory Store、3 イベント)

​

vault.*(Vault、3 イベント)

​

vault_credential.*(認証情報管理、5 イベント)

​

付録 A: クイックスタートガイド

​

ステップ 1: Webhook エンドポイントを作成する

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/qoder",
    "description": "Production webhook",
    "events": ["session.status_idled", "session.thread_idled"]
  }'

​

ステップ 2: signing_secret を保存する

​

ステップ 3: 受信側を実装する

1. Webhook-Signature 署名を検証する
2. イベントの id を使用して冪等な重複排除を行う
3. 受信を確認するために 200 OK を返す
4. ビジネスロジックを非同期に処理する(タイムアウトを回避する)

​

ステップ 4: テストイベントを送信する

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints/{id}/test \
  -H "Authorization: Bearer $PAT"

​

ステップ 5: 検証して本番稼働する

​

付録 B: ベストプラクティス