​

webhooks

orc webhooks は、Workspaceで発生したイベントを外部サービスへHTTP POSTで通知するWebhookを管理するコマンドです。通知先の一覧と詳細を表示し、HTTPS URLと購読イベントを登録して、URL・購読イベント・有効状態を変更したり、通知先を削除したりできます。詳細には直近に記録された送信状態も含まれます。

実行前に orc auth login でサインインするか、利用可能なAPIキーを設定してください。操作対象のWorkspaceを --workspace または ORCHESTOR_WORKSPACE_ID で指定します。現在の認証情報がそのWorkspaceにアクセスできる必要があり、APIキーによる作成・変更・削除には書き込みscopeが必要です。新規登録では署名secretを保存するための、新しいローカルファイルのパスも指定します。

対象のWorkspaceに登録された通知先を表示します。

購読できるイベントは次の3種類です。* を指定すると、通知先にすべてのイベントを配信します。

通知先は1つのWorkspaceに属します。対象は --workspace で選びます。イベントは --events job.completed,job.failed のようにCSVで指定するか、標準入力の events 配列に記述してください。

対象のWorkspaceに登録された通知先のID、URL、購読イベント、有効状態、作成・更新日時を表示します。署名secretは返しません。--json または --format json でJSON envelopeとして取得できます。

通知先一覧をJSONで取得します。

HTTPSの url と購読する events を指定して通知先を登録します。JSONを --stdin で渡すか、--url とCSV形式の --events を指定します。events を省略すると * が設定され、すべてのイベントを購読します。登録直後の通知先は有効です。

署名secretは登録時にのみ返されます。--output に未作成のファイルパスを指定して保存してください。この操作では通常の応答出力とは異なり、secretを所有者だけが読み書きできるファイルへ保存し、標準出力にはsecretを伏せた登録結果を返します。既存ファイルは上書きしません。

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。任意。

(required) HTTPS URL to receive webhook POST requests.; max 2048 chars

型: string。任意。

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。任意。

2種類のイベントを購読し、署名secretを新しいファイルへ保存します。

通知先IDを指定して設定と last_delivery を取得します。送信記録がある場合は状態 pending・delivered・failed、試行回数、最終試行日時、イベント名が含まれます。記録がない場合の last_delivery は null です。署名secretやイベント本文は返しません。

通知先の設定と直近の送信記録を取得します。

通知先IDを指定し、url・events・active のうち入力した項目だけを変更します。省略した項目は保持します。少なくとも1項目が必要で、署名secretの変更や再取得には使用できません。Booleanは --active false のように値を指定します。

Body field: url; max 2048 chars

型: string。任意。

Body field: events; csv of: *|job.completed|job.failed|collection.completed

型: string。任意。

Body field: active

型: string。任意。

通知先の設定を保持して、イベント送信を無効にします。

JSONに指定した項目だけを変更します。

通知先IDを指定して登録を削除します。対話時は確認を求め、--yes で確認を省略できます。非対話で実行する場合は --yes が必要です。成功すると deleted: true を返します。削除した通知先は、その後のイベント通知の対象から外れます。

確認後に通知先を削除します。

非対話で通知先を削除します。

url は必須です。events は配列で指定します。URLにユーザー名・パスワードを含めたり、ローカルやプライベートネットワークの通知先を使用したりすることはできません。

登録する通知先をJSONで指定します。

署名secretをチャット、ログ、共有リポジトリへ貼り付けないでください。ファイルの内容は通知の署名検証に使用します。

JSONから登録し、署名secretを保存します。

url と active は保持されます。空のJSON objectや、未定義のイベント名は使用できません。

通知先の購読イベントだけを変更します。

APIへ登録requestを送りません。プレビューは署名secretなどの秘密値を伏せます。サーバーの権限確認、通知先への疎通、実際のイベント配信の成功を確認する操作ではありません。

登録内容を送信前に確認します。

有効な通知先に、購読対象のイベントがHTTP POSTで送られます。通知本文は id・type・api_version・created・data.object を含むJSONです。登録自体がテスト通知を送信することはありません。

受信側は保存した署名secretを使用し、Webhook-Signature ヘッダーの t=<timestamp>,v1=<signature> を検証します。署名は <timestamp>.<元のrequest本文> に対するHMAC-SHA256です。JSONを再構成する前の本文を使ってください。

送信先は公開ネットワークに解決されるHTTPS URLに限られます。配信時にもアドレスを確認し、リダイレクトには追従しません。受信側はリダイレクトを介さないURLを登録してください。送信結果は orc webhooks get <webhook-id> の last_delivery で確認できます。

orc auth login と、指定したWorkspaceにアクセスできる認証情報を確認してください。APIキーで変更する場合は書き込みscopeが必要です。--workspace を別のIDへ変更するだけで、権限が追加されることはありません。

同じWorkspaceで orc webhooks list を実行し、通知先IDを確認してください。削除済みの通知先や、別のWorkspaceの通知先は取得・変更できません。

HTTPSの公開URLを指定し、URLに認証情報を埋め込まないでください。events は上記の名前または * を使用します。更新は url・events・active のいずれかを含めてください。

--output に新しいファイルのパスを指定し、親ディレクトリへ書き込めることを確認してください。既存ファイルは上書きしません。一覧や詳細からsecretを再表示することはできません。保存ファイルを紛失した場合は、受信側の設定を含めて通知先の再登録を検討してください。

通知先の active、購読イベント、last_delivery を確認してください。last_delivery: null は記録されたイベント送信がないことを示します。受信側のHTTPS URLがリダイレクトせず、署名検証に正しいsecretと元の本文を使っていることも確認してください。--dry-run は配信テストを行いません。

Workspaceへのアクセスが必要です。APIキーの操作には対応する読み取り・書き込みscopeが適用されます。別のWorkspaceの通知先IDを指定しても取得・変更・削除はできません。

orc webhooks では、次のグローバルオプションを使用できます。

各オプションの詳細と使用例は、グローバルオプションを参照してください。