--- title: webhooks description: 外部連携先へのイベント通知を設定する。 canonical_url: https://orchestor.io/docs/cli/webhooks markdown_url: https://orchestor.io/docs/cli/webhooks.md contentType: reference --- # webhooks `orc webhooks` は、Workspaceで発生したイベントを外部サービスへHTTP POSTで通知するWebhookを管理するコマンドです。通知先の一覧と詳細を表示し、HTTPS URLと購読イベントを登録して、URL・購読イベント・有効状態を変更したり、通知先を削除したりできます。詳細には直近に記録された送信状態も含まれます。実行前に `orc auth login` でサインインするか、利用可能なAPIキーを設定してください。操作対象のWorkspaceを `--workspace` または `ORCHESTOR_WORKSPACE_ID` で指定します。現在の認証情報がそのWorkspaceにアクセスできる必要があり、APIキーによる作成・変更・削除には書き込みscopeが必要です。新規登録では署名secretを保存するための、新しいローカルファイルのパスも指定します。 ## 使い方 ```bash title="terminal" orc webhooks list --workspace ``` *対象のWorkspaceに登録された通知先を表示します。* ## 購読イベントとWorkspace 購読できるイベントは次の3種類です。`*` を指定すると、通知先にすべてのイベントを配信します。 | イベント | 内容 | | --- | --- | | `job.completed` | ジョブ完了 | | `job.failed` | ジョブ失敗 | | `collection.completed` | コレクション完了 | 通知先は1つのWorkspaceに属します。対象は `--workspace` で選びます。イベントは `--events job.completed,job.failed` のようにCSVで指定するか、標準入力の `events` 配列に記述してください。 ## サブコマンド ### `list` 対象のWorkspaceに登録された通知先のID、URL、購読イベント、有効状態、作成・更新日時を表示します。署名secretは返しません。`--json` または `--format json` でJSON envelopeとして取得できます。 ```bash title="terminal" orc webhooks list [options] ``` #### 使用例 ```bash title="terminal" orc webhooks list --workspace --format json ``` *通知先一覧をJSONで取得します。* ### `create` HTTPSの `url` と購読する `events` を指定して通知先を登録します。JSONを `--stdin` で渡すか、`--url` とCSV形式の `--events` を指定します。`events` を省略すると `*` が設定され、すべてのイベントを購読します。登録直後の通知先は有効です。署名secretは登録時にのみ返されます。`--output` に未作成のファイルパスを指定して保存してください。この操作では通常の応答出力とは異なり、secretを所有者だけが読み書きできるファイルへ保存し、標準出力にはsecretを伏せた登録結果を返します。既存ファイルは上書きしません。 ```bash title="terminal" orc webhooks create [options] ``` #### 固有のオプション ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. 型: `string`。任意。 ```bash title="terminal" orc webhooks create --idempotency-key ``` ##### `--url` (required) HTTPS URL to receive webhook POST requests.; max 2048 chars 型: `string`。任意。 ```bash title="terminal" orc webhooks create --url ``` ##### `--events` Event types to subscribe to. Use `*` to receive all events. Supported events: `job.completed`, `job.failed`, `collection.completed`.; csv of: *|job.completed|job.failed|collection.completed 型: `string`。任意。 ```bash title="terminal" orc webhooks create --events ``` #### 使用例 ```bash title="terminal" orc webhooks create --url https://example.com/webhooks/orchestor --events job.completed,job.failed --workspace --output ./webhook-signing-secret.txt ``` *2種類のイベントを購読し、署名secretを新しいファイルへ保存します。* ### `get` 通知先IDを指定して設定と `last_delivery` を取得します。送信記録がある場合は状態 `pending`・`delivered`・`failed`、試行回数、最終試行日時、イベント名が含まれます。記録がない場合の `last_delivery` は `null` です。署名secretやイベント本文は返しません。 ```bash title="terminal" orc webhooks get [options] ``` #### 使用例 ```bash title="terminal" orc webhooks get --workspace --json ``` *通知先の設定と直近の送信記録を取得します。* ### `update` 通知先IDを指定し、`url`・`events`・`active` のうち入力した項目だけを変更します。省略した項目は保持します。少なくとも1項目が必要で、署名secretの変更や再取得には使用できません。Booleanは `--active false` のように値を指定します。 ```bash title="terminal" orc webhooks update [options] ``` #### 固有のオプション ##### `--url` Body field: url; max 2048 chars 型: `string`。任意。 ```bash title="terminal" orc webhooks update --url ``` ##### `--events` Body field: events; csv of: *|job.completed|job.failed|collection.completed 型: `string`。任意。 ```bash title="terminal" orc webhooks update --events ``` ##### `--active` Body field: active 型: `string`。任意。 ```bash title="terminal" orc webhooks update --active ``` #### 使用例 ```bash title="terminal" orc webhooks update --active false --workspace ``` *通知先の設定を保持して、イベント送信を無効にします。* ```bash title="terminal" orc webhooks update --stdin --workspace < webhook-update.json ``` *JSONに指定した項目だけを変更します。* ### `delete` 通知先IDを指定して登録を削除します。対話時は確認を求め、`--yes` で確認を省略できます。非対話で実行する場合は `--yes` が必要です。成功すると `deleted: true` を返します。削除した通知先は、その後のイベント通知の対象から外れます。 ```bash title="terminal" orc webhooks delete [options] ``` #### 使用例 ```bash title="terminal" orc webhooks delete --workspace ``` *確認後に通知先を削除します。* ```bash title="terminal" orc webhooks delete --workspace --yes ``` *非対話で通知先を削除します。* ## 使用例 ### 登録する通知先をJSONで指定します。 `url` は必須です。`events` は配列で指定します。URLにユーザー名・パスワードを含めたり、ローカルやプライベートネットワークの通知先を使用したりすることはできません。 ```json title="webhook.json" { "url": "https://example.com/webhooks/orchestor", "events": [ "job.completed", "job.failed" ] } ``` *登録する通知先をJSONで指定します。* ### JSONから登録し、署名secretを保存します。署名secretをチャット、ログ、共有リポジトリへ貼り付けないでください。ファイルの内容は通知の署名検証に使用します。 ```bash title="terminal" orc webhooks create --stdin --workspace --output ./webhook-signing-secret.txt < webhook.json ``` *JSONから登録し、署名secretを保存します。* ### 通知先の購読イベントだけを変更します。 `url` と `active` は保持されます。空のJSON objectや、未定義のイベント名は使用できません。 ```json title="webhook-update.json" { "events": [ "collection.completed" ] } ``` *通知先の購読イベントだけを変更します。* ### 登録内容を送信前に確認します。 APIへ登録requestを送りません。プレビューは署名secretなどの秘密値を伏せます。サーバーの権限確認、通知先への疎通、実際のイベント配信の成功を確認する操作ではありません。 ```bash title="terminal" orc webhooks create --stdin --workspace --output ./webhook-signing-secret.txt --dry-run < webhook.json ``` *登録内容を送信前に確認します。* ## 通知と署名の仕組み有効な通知先に、購読対象のイベントがHTTP POSTで送られます。通知本文は `id`・`type`・`api_version`・`created`・`data.object` を含むJSONです。登録自体がテスト通知を送信することはありません。受信側は保存した署名secretを使用し、`Webhook-Signature` ヘッダーの `t=,v1=` を検証します。署名は `.<元のrequest本文>` に対するHMAC-SHA256です。JSONを再構成する前の本文を使ってください。送信先は公開ネットワークに解決されるHTTPS URLに限られます。配信時にもアドレスを確認し、リダイレクトには追従しません。受信側はリダイレクトを介さないURLを登録してください。送信結果は `orc webhooks get ` の `last_delivery` で確認できます。 ## トラブルシューティング ### 認証または権限エラー `orc auth login` と、指定したWorkspaceにアクセスできる認証情報を確認してください。APIキーで変更する場合は書き込みscopeが必要です。`--workspace` を別のIDへ変更するだけで、権限が追加されることはありません。 ### 通知先が見つからない同じWorkspaceで `orc webhooks list` を実行し、通知先IDを確認してください。削除済みの通知先や、別のWorkspaceの通知先は取得・変更できません。 ### URLやイベントが受け付けられない HTTPSの公開URLを指定し、URLに認証情報を埋め込まないでください。`events` は上記の名前または `*` を使用します。更新は `url`・`events`・`active` のいずれかを含めてください。 ### 署名secretを保存できない `--output` に新しいファイルのパスを指定し、親ディレクトリへ書き込めることを確認してください。既存ファイルは上書きしません。一覧や詳細からsecretを再表示することはできません。保存ファイルを紛失した場合は、受信側の設定を含めて通知先の再登録を検討してください。 ### 通知が届かない通知先の `active`、購読イベント、`last_delivery` を確認してください。`last_delivery: null` は記録されたイベント送信がないことを示します。受信側のHTTPS URLがリダイレクトせず、署名検証に正しいsecretと元の本文を使っていることも確認してください。`--dry-run` は配信テストを行いません。 ## 必要な権限 Workspaceへのアクセスが必要です。APIキーの操作には対応する読み取り・書き込みscopeが適用されます。別のWorkspaceの通知先IDを指定しても取得・変更・削除はできません。 ## グローバルオプション `orc webhooks` では、次の[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を使用できます。 - [`--help`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%98%E3%83%AB%E3%83%97) - [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AF%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%9A%E3%83%BC%E3%82%B9) - [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B) - [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B) - [`--format`](https://orchestor.io/docs/cli/global-flags.md#%E5%87%BA%E5%8A%9B%E5%BD%A2%E5%BC%8F) - [`--field`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA) - [`--fields`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA) - [`--raw`](https://orchestor.io/docs/cli/global-flags.md#%E5%80%A4%E3%81%A0%E3%81%91%E3%82%92%E5%87%BA%E5%8A%9B) - [`--output`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%B8%E3%81%AE%E5%87%BA%E5%8A%9B) - [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%9A%E3%83%BC%E3%82%B8%E9%80%81%E3%82%8A) - [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%81%AE%E4%BA%8B%E5%89%8D%E7%A2%BA%E8%AA%8D) - [`--yes`](https://orchestor.io/docs/cli/global-flags.md#%E7%A2%BA%E8%AA%8D%E3%81%AE%E7%9C%81%E7%95%A5) - [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B) - [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B) - [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#%E3%81%99%E3%81%B9%E3%81%A6%E3%81%AE%E3%83%9A%E3%83%BC%E3%82%B8%E3%82%92%E5%8F%96%E5%BE%97) - [`--timing`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E6%99%82%E9%96%93) 各オプションの詳細と使用例は、[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を参照してください。 ## 関連項目 - [`orc api`](https://orchestor.io/docs/cli/api.md)：認証付きAPI requestを扱います。 - [グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)：`--workspace`・`--stdin`・`--json`・`--dry-run` などの共通仕様を確認できます。 --- [Documentation index](https://orchestor.io/docs/llms.txt)