Webhooks

​

概要

• イベント駆動型プッシュ — リソースの状態変化時に能動的に通知し、クライアント側のポーリングは不要
• envelope 構造 — 統一された BetaWebhookEvent { id, created_at, data, type:"event" } フォーマット
• 配信セマンティクス — 少なくとも 1 回(at-least-once)の保証、指数バックオフによるリトライ

​

ドメインタイプ

​

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

​

Webhook Session Updated Event Data

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

​

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 }
  • id: string イベントをトリガーした Agent ID。
  • type: "agent.created"
    • "agent.created"
    Agent が正常に作成されたときにトリガーされます。システムは POST /agents により Agent が作成された後にこのイベントを送信します。

​

Webhook Agent Updated Event Data

• WebhookAgentUpdatedEventData object { id, type }
  • id: string イベントをトリガーした Agent ID。
  • type: "agent.updated"
    • "agent.updated"
    Agent の設定が更新されたときにトリガーされます。

​

Webhook Agent Archived Event Data

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

​

Webhook Agent Deleted Event Data

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

​

Deployment Run イベント

• WebhookDeploymentRunStartedEventData object { id, type: "deployment_run.started" }
• WebhookDeploymentRunSucceededEventData object { id, type: "deployment_run.succeeded" }
• WebhookDeploymentRunFailedEventData object { id, type: "deployment_run.failed" }

​

Webhook エンドポイント API

Authorization: Bearer $QODER_ACCESS_TOKEN

​

POST /webhook_endpoints

{
  "id": "5fc05310-4d9c-447e-a4b8-f124f17e1ff0",
  "url": "https://webhook.site/your-unique-path",
  "description": "quickstart demo",
  "events": ["session.status_idled", "session.thread_idled"],
  "active": true,
  "signing_secret": "whsec_BfJDodFEzmkdjAUf19-_XthSq6KbPKmRjfm9KFWMIuk",
  "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 $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.site/your-unique-path",
    "description": "quickstart demo",
    "events": ["session.status_idled", "session.thread_idled"]
  }'

​

GET /webhook_endpoints

{
  "data": [
    {
      "id": "700e7789-edab-41cb-b60a-210d0df38ab6",
      "url": "https://myapp.example.com/hooks/qoder",
      "description": "prod app hook",
      "events": ["session.status_idled", "session.thread_idled"],
      "active": true,
      "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 $QODER_ACCESS_TOKEN"

​

GET /webhook_endpoints/{id}

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

​

PUT /webhook_endpoints/{id}

curl -X PUT https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["session.status_idled", "session.thread_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 $QODER_ACCESS_TOKEN"

​

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 $QODER_ACCESS_TOKEN"

​

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 $QODER_ACCESS_TOKEN"

​

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 $QODER_ACCESS_TOKEN"

​

GET /webhook_events

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

​

GET /webhook_events/{id}

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

​

エラーレスポンス形式

{
  "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 構造」を参照）

​

リクエストヘッダー

​

リトライ戦略

​

レスポンスコードの処理

​

自動デグレード

• エンドポイント URL に到達できるか
• SSL 証明書が有効か
• サーバーが正常に応答しているか

​

サポート対象のイベントタイプ

​

envelope 構造

​

基本 envelope 構造

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

​

Thread イベントの envelope

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

​

フィールドの説明

​

冪等性の処理

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

​

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

​

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

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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: 受信側を実装する

1. JSON ペイロードを解析し、type に応じてイベントを処理する
2. イベントの id を使用して冪等な重複排除を行う
3. 受信確認として 200 OK を返す
4. ビジネスロジックを非同期に処理する（タイムアウトを回避するため）

​

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

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

​

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

​

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