Webhook - Qoder

Webhook は現在 Beta 機能です。API、フィールド、および動作は今後のバージョンで変更される可能性があります。

Webhook Endpoint には受信 URL と購読イベントが保存されます。イベントが発生すると、Qoder Cloud Agents は Endpoint に POST リクエストを送信します。Webhook は、長時間接続で待機できない Schedule Run などの非同期結果の受信に適しています。これらの API で管理できるのは、現在の個人スペースまたは企業 Workspace で Forward Mode を使用して作成した Endpoint のみです。別のスペースや Mode で作成した Endpoint は一覧に表示されず、これらの API では操作できません。

API

メソッド	パス	説明
`POST`	`/api/v1/forward/webhook/endpoints`	Endpoint を作成する
`GET`	`/api/v1/forward/webhook/endpoints`	Endpoint の一覧を取得する
`GET`	`/api/v1/forward/webhook/endpoints/{endpoint_id}`	Endpoint を取得する
`PUT`	`/api/v1/forward/webhook/endpoints/{endpoint_id}`	Endpoint を更新する
`DELETE`	`/api/v1/forward/webhook/endpoints/{endpoint_id}`	Endpoint を削除する
`POST`	`/api/v1/forward/webhook/endpoints/{endpoint_id}/enable`	Endpoint を有効化する
`POST`	`/api/v1/forward/webhook/endpoints/{endpoint_id}/disable`	Endpoint を無効化する
`POST`	`/api/v1/forward/webhook/endpoints/{endpoint_id}/test`	テストイベントを送信する

認証

Webhook Endpoint は管理リソースです。これらの API は Qoder PAT または管理者 Service Account Token を受け付けます。

Authorization: Bearer <PAT or administrator SAT>

Identity レベルの Service Account Token では Webhook Endpoint を管理できません。

公開イベント

Forward は現在、次の 29 種類の公開イベントをサポートしています。これは Forward コンソールの購読カタログと一致します。同じ Endpoint で Schedule のビジネスイベントと Managed Agents のリソースイベントを同時に購読できます。Endpoint を作成または更新するときは、表の完全なイベント名を events 配列に指定してください。

Schedule と Schedule Run

イベントタイプ	トリガー
`forward.schedule.created`	Schedule が正常に作成されたとき。
`forward.schedule_run.succeeded`	Schedule Run が正常に完了し、`data.status` が `completed` のとき。
`forward.schedule_run.failed`	Schedule Run が失敗し、`data.status` が `failed` のとき。

Schedule Run の実行結果はチャネルへの配信結果とは異なります。チャネルへの配信状態は data.push_status で示されます。これら 3 種類のイベントの data には Schedule の作成元が含まれます。フィールドの説明と例は Webhook イベントを受信するを参照してください。

Session

イベントタイプ	トリガー
`session.status_run_started`	Session が 1 回の実行を開始したとき。
`session.status_idled`	今回の実行が終了またはキャンセルされ、Session がアイドル状態になったとき。
`session.status_terminated`	Session が終了されたとき。
`session.updated`	Session のタイトルやメタデータなどの属性が更新されたとき。
`session.deleted`	Session が削除されたとき。

session.status_idled はセッションがアイドル状態になったことを示すもので、業務処理の成功を意味しません。Session の出力とステータスを取得して結果を確認してください。

Session Thread

イベントタイプ	トリガー
`session.thread_created`	Session 内に新しいスレッドが作成されたとき。
`session.thread_idled`	スレッドの今回の実行が終了、中断、またはツール結果などの外部アクションを待つために一時停止したとき。
`session.thread_terminated`	スレッドが終了されたとき。

スレッドイベントの data.id は所属する Session ID で、data.session_thread_id が個々のスレッドを識別します。session.thread_idled はスレッドのタスク完了を必ずしも意味しません。外部アクションを待っている間、スレッドのステータスは blocked です。

Agent

イベントタイプ	トリガー
`agent.created`	Managed Agent が正常に作成されたとき。
`agent.updated`	Managed Agent の設定が更新されたとき。
`agent.archived`	Managed Agent がアーカイブされたとき。
`agent.deleted`	Managed Agent が削除されたとき。

ここでの Agent は Managed Agents のリソースを指し、Forward Template ではありません。これらのイベントは Template のライフサイクル変更を示すものではありません。

Environment

イベントタイプ	トリガー
`environment.created`	Environment が正常に作成されたとき。
`environment.updated`	Environment の設定が更新されたとき。
`environment.archived`	Environment がアーカイブされたとき。
`environment.deleted`	Environment が削除されたとき。

Memory Store

イベントタイプ	トリガー
`memory_store.created`	Memory Store が正常に作成されたとき。
`memory_store.archived`	Memory Store がアーカイブされたとき。
`memory_store.deleted`	Memory Store が削除されたとき。

Vault と Vault Credential

イベントタイプ	トリガー
`vault.created`	Vault が正常に作成されたとき。
`vault.archived`	Vault がアーカイブされたとき。
`vault.deleted`	Vault が削除されたとき。
`vault_credential.created`	Vault Credential が正常に作成されたとき。
`vault_credential.archived`	認証情報がアーカイブされたとき。所属する Vault のアーカイブによるカスケードアーカイブを含みます。
`vault_credential.deleted`	認証情報が削除されたとき。所属する Vault の削除によるカスケード削除を含みます。
`vault_credential.refresh_failed`	OAuth 認証情報の更新が失敗したとき。

認証情報イベントの data.id は認証情報 ID で、data.vault_id は所属する Vault の ID です。イベントに認証情報のシークレットは含まれません。

購読ルールとテストイベント

events には 1 件以上が必要で、完全なイベント名またはグローバルワイルドカード * を指定できます。forward.* や session.* などの前方一致ワイルドカードはサポートされません。
* を指定すると、現在および今後配信可能になるすべてのイベントを購読します。本番環境では、必要な公開イベントを明示的に購読し、まだ認識できないイベントタイプにも対応できるようにしてください。
API は namespace.name 形式のイベント名を受け付けますが、そのイベントが必ず発生することを意味しません。上記の公開カタログにあるイベントのみ Forward の配信契約の対象です。
Forward は Deployment と Deployment Run のイベントを公開しません。Managed Agents のすべてのイベントを Forward がサポートするイベントと見なさないでください。
webhook.test はテストイベントを送信する API が生成する対象指定のテストイベントです。購読一覧に含める必要はなく、上記 29 種類のビジネスイベントおよびリソースイベントには含まれません。

たとえば、セッションのアイドル通知と Schedule Run の最終結果を同時に受信する場合は次のように指定します。

{
  "events": [
    "session.status_idled",
    "forward.schedule_run.succeeded",
    "forward.schedule_run.failed"
  ]
}

イベントペイロード、署名検証、冪等処理については、Webhook イベントを受信するを参照してください。

利用手順

公開 HTTPS POST リクエストを受信できる URL を用意します。
Endpoint を作成し、作成レスポンスの signing_secret を安全に保存します。
テスト API を呼び出して、接続と署名処理を確認します。
必要なイベントを購読し、Webhook-ID で重複配信を排除します。

Webhook は少なくとも 1 回配信されるため、同じイベントが複数回届く場合があります。速やかに 2xx を返し、時間のかかる処理は非同期で実行してください。

​API

​認証

​公開イベント

​Schedule と Schedule Run

​Session

​Session Thread

​Agent

​Environment

​Memory Store

​Vault と Vault Credential

​購読ルールとテストイベント

​利用手順

API

認証

公開イベント

Schedule と Schedule Run

Session

Session Thread

Agent

Environment

Memory Store

Vault と Vault Credential

購読ルールとテストイベント

利用手順