Webhooks
Manage webhook targets with helios webhook. Create a target, verify it with a test event, rotate its secret, and read or resend its deliveries.
The helios webhook commands call the same API as Settings > Webhooks, with your API key. The
same permissions apply. A command you are not allowed to run prints the
403 error and exits with a non-zero code.
| Command | What it does |
|---|---|
list | List the targets you can see. |
create | Create a target. It stays unverified until a test gets a 2xx. |
update <target-id> | Change the name, URL, events or payload version. |
pause <target-id>, resume <target-id> | Stop and restart deliveries. |
delete <target-id> | Delete a target and its delivery history. |
secret show <target-id>, secret rotate <target-id> | Reveal or replace the signing secret. |
test <target-id> | Send a test event and print the result. |
deliveries <target-id> | List deliveries with filters. |
resend <target-id> <delivery-id> | Send one delivery again. |
Create and verify a target
Create a target in the active project, or in your personal scope when the active project is your
personal project (the default right after helios auth login). Pass the event types as a
comma-separated list. See event types for every type.
helios webhook create --name "Run failures" \
--url https://hooks.example.com/helios \
--events workflow.run.failed,workflow.run.cancelledThe output includes the signing secret. Save it now. You can reveal it again later with
secret show.
| Flag | What it does |
|---|---|
--name <name> | Target name. Required. |
--url <url> | HTTPS URL on port 443. Required. |
--events <types> | Comma-separated event types. Required. |
--scope <scope> | project, org or personal. Defaults to project, or personal when the active project is your personal project. |
--project <id> | Project for a project target. Defaults to the active project. |
--payload-version <version> | Payload version. Defaults to the latest. |
--idempotency-key <key> | Send the same key again to get the first target back instead of a second one. |
The new target is unverified. Send a test event to turn it on.
helios webhook test <target-id>The command prints the delivery ID, the HTTP status, the failure reason and the target status. It
exits with a non-zero code when the test did not get a 2xx. A target accepts 10 test events per
hour.
Create an organization target or a personal target with --scope.
helios webhook create --scope personal --name "My chats" \
--url https://hooks.example.com/chats --events chat.turn.completed,chat.turn.failedList and update targets
helios webhook list
helios webhook list --scope org
helios webhook list --project <id>The table shows each target's status and reason, its events, its success rate over the last 24 hours and your role on it.
helios webhook update <target-id> --events workflow.run.failed,workflow.run.succeeded
helios webhook update <target-id> --payload-version 2026-10-01--events replaces the whole list. A new --url sets the target back to unverified, so run
test again after it.
Pause, resume and delete
helios webhook pause <target-id>
helios webhook resume <target-id>
helios webhook delete <target-id> --yespause and delete ask for confirmation unless you pass --yes. While a target is paused, its
events are dropped and cannot be resent. Deliveries that were waiting for a retry end with
target_disabled. You can resend those after you resume. See
target status.
Turn back on, Confirm URL and Resend all failed since are in Settings > Webhooks.
Signing secret
helios webhook secret show <target-id>
helios webhook secret rotate <target-id>secret show asks for confirmation. Pass --yes to skip it in a script. With --no-input and no
--yes, it stops without showing the secret. Every reveal is logged with your user ID. After secret rotate, the previous secret stays valid for 24 hours. See
check the signature.
Deliveries
List a target's deliveries from the last 24 hours.
helios webhook deliveries <target-id>Narrow the list.
helios webhook deliveries <target-id> --status failed
helios webhook deliveries <target-id> --event-type workflow.run.failed --since 2026-10-01T00:00:00Z
helios webhook deliveries <target-id> --resource-id <run-id>| Flag | What it does |
|---|---|
--status <status> | pending, sending, succeeded or failed. |
--event-type <type> | One event type. |
--since <time>, --until <time> | Time range in ISO 8601. Defaults to the last 24 hours. |
--event-id <id> | One event, the same as the webhook-id header. |
--resource-id <id> | Events about one resource, such as a run ID. |
--page <n>, --page-size <n> | Page through the results, at most 100 per page. |
The table ends with the total count. A total of 10,000+ means there are more. Narrow the filters to
count them. With --json you get every attempt of each delivery.
Send one delivery again with the same event ID.
helios webhook resend <target-id> <delivery-id>A delivery that is still retrying cannot be resent. Each person can resend 60 times per hour. See delivery and retries for the failure reasons.
Last updated on
Projects and access
Pick the active project with project use, HELIOS_PROJECT, or --project. Share resources, audit access, and manage groups and service accounts from the CLI.
Projects and sharing
A project groups related workflows, chats, integrations, and variables, and is the unit of access control in Helios.