​

webhooks

orc webhooks manages Webhooks that notify external services of Workspace events through HTTP POST. List and inspect destinations, register HTTPS URLs and subscribed events, change URLs, subscriptions, or active status, and delete destinations. Details also include the most recently recorded delivery status.

Before running commands, sign in with orc auth login or configure an available API key. Specify the target Workspace with --workspace or ORCHESTOR_WORKSPACE_ID. Your credentials must have access to that Workspace. API keys need write scope to create, update, or delete destinations. New registrations also require a path to a new local file for the signing secret.

Display destinations registered in the target Workspace.

The following three event types are available. Specify * to deliver all events to the destination.

A destination belongs to one Workspace. Select it with --workspace. Specify events as CSV, such as --events job.completed,job.failed, or in the events array on standard input.

Display destination IDs, URLs, subscribed events, active status, and creation and update timestamps for the target Workspace. Signing secrets are excluded. Use --json or --format json to receive a JSON envelope.

Retrieve destinations as JSON.

Register a destination with an HTTPS url and subscribed events. Pass JSON through --stdin or specify --url and CSV --events. Omitting events sets *, subscribing to all events. New destinations are active.

The signing secret is returned only at registration. Specify a path to a file that does not exist using --output. Unlike normal response output, this operation saves the secret to a file readable and writable only by its owner and returns the registration result on stdout with the secret redacted. Existing files are not overwritten.

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.

Type: string. Optional.

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

Type: string. Optional.

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

Type: string. Optional.

Subscribe to two event types and save the signing secret to a new file.

Specify a destination ID to retrieve its configuration and last_delivery. If a delivery is recorded, this includes status (pending, delivered, or failed), attempt count, last attempt time, and event name. last_delivery is null when no delivery is recorded. Signing secrets and event bodies are excluded.

Retrieve destination settings and the latest delivery record.

Specify a destination ID and change only the supplied url, events, or active fields. Omitted fields are preserved. At least one field is required. This operation cannot change or retrieve the signing secret. Supply a value for booleans, such as --active false.

Body field: url; max 2048 chars

Type: string. Optional.

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

Type: string. Optional.

Body field: active

Type: string. Optional.

Disable event delivery while preserving destination settings.

Change only fields supplied in JSON.

Delete a registration by destination ID. Interactive execution asks for confirmation; --yes skips it. Non-interactive execution requires --yes. Success returns deleted: true. Deleted destinations are excluded from subsequent event notifications.

Delete a destination after confirmation.

Delete a destination non-interactively.

url is required. Specify events as an array. URLs containing a username or password, and destinations on local or private networks, are not allowed.

Specify a destination in JSON.

Do not paste signing secrets into chat, logs, or shared repositories. Use the file contents to verify notification signatures.

Register from JSON and save the signing secret.

url and active are preserved. An empty JSON object or undefined event names are not allowed.

Change only the subscribed events.

No registration request is sent to the API. The preview redacts secrets such as the signing secret. It does not check server permissions, connectivity to the destination, or successful delivery of an actual event.

Preview registration before sending.

HTTP POST sends subscribed events to active destinations. The notification body is JSON containing id, type, api_version, created, and data.object. Registration does not send a test notification.

The receiver uses the saved signing secret to verify t=<timestamp>,v1=<signature> in the Webhook-Signature header. The signature is HMAC-SHA256 over <timestamp>.<original request body>. Use the original body before reconstructing JSON.

Destinations must be HTTPS URLs resolving to the public network. Addresses are checked at delivery time as well, and redirects are not followed. Register a receiver URL that does not redirect. Check results in last_delivery from orc webhooks get <webhook-id>.

Check orc auth login and credentials that can access the specified Workspace. API key changes require write scope. Changing --workspace to another ID does not add permissions.

Run orc webhooks list in the same Workspace and check the destination ID. Deleted destinations and destinations in another Workspace cannot be retrieved or updated.

Specify a public HTTPS URL without embedded credentials. Use the event names above or * for events. Updates must include at least one of url, events, or active.

Specify a new file path with --output and check that the parent directory is writable. Existing files are not overwritten. Lists and details cannot display the secret again. If the saved file is lost, consider registering the destination again and updating the receiver configuration.

Check the destination’s active status, subscriptions, and last_delivery. last_delivery: null means there is no recorded event delivery. Check that the receiver’s HTTPS URL does not redirect and signature verification uses the correct secret and original body. --dry-run does not test delivery.

Access to the Workspace is required. Corresponding read and write scopes apply to API key operations. Specifying a destination ID from another Workspace does not let you retrieve, update, or delete it.

The following global options can be used with orc webhooks:

For details and examples, see global options.