---
title: webhooks
description: Configure event notifications to external integrations.
canonical_url: https://orchestor.io/docs/en/cli/webhooks
markdown_url: https://orchestor.io/docs/en/cli/webhooks.md
contentType: reference
---

# 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.

## Usage

```bash title="terminal"
orc webhooks list --workspace <workspace-id>
```

*Display destinations registered in the target Workspace.*

## Subscribed events and Workspace

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

| Event | Description |
| --- | --- |
| `job.completed` | Job completed |
| `job.failed` | Job failed |
| `collection.completed` | Collection completed |

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.

## Subcommands

### `list`

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.

```bash title="terminal"
orc webhooks list [options]
```

#### Examples

```bash title="terminal"
orc webhooks list --workspace <workspace-id> --format json
```

*Retrieve destinations as JSON.*

### `create`

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.

```bash title="terminal"
orc webhooks create [options]
```

#### Unique 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.

Type: `string`. Optional.

```bash title="terminal"
orc webhooks create --idempotency-key <value>
```

##### `--url`

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

Type: `string`. Optional.

```bash title="terminal"
orc webhooks create --url <value>
```

##### `--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

Type: `string`. Optional.

```bash title="terminal"
orc webhooks create --events <value>
```

#### Examples

```bash title="terminal"
orc webhooks create --url https://example.com/webhooks/orchestor --events job.completed,job.failed --workspace <workspace-id> --output ./webhook-signing-secret.txt
```

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

### `get`

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.

```bash title="terminal"
orc webhooks get <id> [options]
```

#### Examples

```bash title="terminal"
orc webhooks get <webhook-id> --workspace <workspace-id> --json
```

*Retrieve destination settings and the latest delivery record.*

### `update`

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`.

```bash title="terminal"
orc webhooks update <id> [options]
```

#### Unique options

##### `--url`

Body field: url; max 2048 chars

Type: `string`. Optional.

```bash title="terminal"
orc webhooks update <id> --url <value>
```

##### `--events`

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

Type: `string`. Optional.

```bash title="terminal"
orc webhooks update <id> --events <value>
```

##### `--active`

Body field: active

Type: `string`. Optional.

```bash title="terminal"
orc webhooks update <id> --active <value>
```

#### Examples

```bash title="terminal"
orc webhooks update <webhook-id> --active false --workspace <workspace-id>
```

*Disable event delivery while preserving destination settings.*

```bash title="terminal"
orc webhooks update <webhook-id> --stdin --workspace <workspace-id> < webhook-update.json
```

*Change only fields supplied in JSON.*

### `delete`

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.

```bash title="terminal"
orc webhooks delete <id> [options]
```

#### Examples

```bash title="terminal"
orc webhooks delete <webhook-id> --workspace <workspace-id>
```

*Delete a destination after confirmation.*

```bash title="terminal"
orc webhooks delete <webhook-id> --workspace <workspace-id> --yes
```

*Delete a destination non-interactively.*

## Examples

### Specify a destination in JSON.

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

```json title="webhook.json"
{
  "url": "https://example.com/webhooks/orchestor",
  "events": [
    "job.completed",
    "job.failed"
  ]
}
```

*Specify a destination in JSON.*

### Register from JSON and save the signing secret.

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

```bash title="terminal"
orc webhooks create --stdin --workspace <workspace-id> --output ./webhook-signing-secret.txt < webhook.json
```

*Register from JSON and save the signing secret.*

### Change only the subscribed events.

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

```json title="webhook-update.json"
{
  "events": [
    "collection.completed"
  ]
}
```

*Change only the subscribed events.*

### Preview registration before sending.

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.

```bash title="terminal"
orc webhooks create --stdin --workspace <workspace-id> --output ./webhook-signing-secret.txt --dry-run < webhook.json
```

*Preview registration before sending.*

## Delivery and signatures

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>`.

## Troubleshooting

### Authentication or permission errors

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.

### A destination is missing

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.

### A URL or event is rejected

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`.

### A signing secret cannot be saved

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.

### Notifications do not arrive

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.

## Permissions

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.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc webhooks`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

## Related

- [`orc api`](https://orchestor.io/docs/cli/api.md): Make authenticated API requests.
- [Global options](https://orchestor.io/docs/cli/global-flags.md): Shared behavior for `--workspace`, `--stdin`, `--json`, `--dry-run`, and other flags.

---

[Documentation index](https://orchestor.io/docs/llms.txt)