Webhooks commands
The 11 koast CLI commands for the Webhooks operations.
Every command is one API operation, named by its operationId. Global flags such as --output and --api-url work on all of them, see CLI commands.
create-webhook-endpoint
Create webhook endpoint. POST /v1/webhooks, API reference.
koast create-webhook-endpoint --url <url> --event-types <event-types> [--json <file|->] [flags]| Flag | Type | Required | Description |
|---|---|---|---|
--url | string | Yes | HTTPS URL Koast POSTs events to. No credentials in the URL; redirects are not followed. At most 2048 characters. |
--event-types | string, repeatable | Yes | Event types this endpoint receives. ping is always delivered by the test send and cannot be subscribed to. One of launch.completed, launch.failed, launch.partially_failed, ad.approved, ad.rejected, delivery.status_changed, metrics.updated, spend.day_closed. At least 1 item. |
--brand-ids | integer, repeatable | No | Only deliver events of these brands. Null delivers events of every brand in the organization. At least 1 item. |
Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.
Example:
koast create-webhook-endpoint --url URL --event-types launch.completeddelete-webhook-endpoint
Delete webhook endpoint. DELETE /v1/webhooks/{endpointId}, API reference.
koast delete-webhook-endpoint --endpoint-id <endpoint-id>| Flag | Type | Required | Description |
|---|---|---|---|
--endpoint-id | string | Yes | The webhook endpoint id (ep_…). At most 64 characters. |
Required scope: write.
Example:
koast delete-webhook-endpoint --endpoint-id ENDPOINT_IDenable-webhook-endpoint
Enable webhook endpoint. POST /v1/webhooks/{endpointId}/enable, API reference.
koast enable-webhook-endpoint --endpoint-id <endpoint-id>| Flag | Type | Required | Description |
|---|---|---|---|
--endpoint-id | string | Yes | The webhook endpoint id (ep_…). At most 64 characters. |
Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one.
Example:
koast enable-webhook-endpoint --endpoint-id ENDPOINT_IDget-webhook-endpoint
Get webhook endpoint. GET /v1/webhooks/{endpointId}, API reference.
koast get-webhook-endpoint --endpoint-id <endpoint-id>| Flag | Type | Required | Description |
|---|---|---|---|
--endpoint-id | string | Yes | The webhook endpoint id (ep_…). At most 64 characters. |
Required scope: read.
Example:
koast get-webhook-endpoint --endpoint-id ENDPOINT_IDget-webhook-secret
Get webhook secret. GET /v1/webhooks/{endpointId}/secret, API reference.
koast get-webhook-secret --endpoint-id <endpoint-id>| Flag | Type | Required | Description |
|---|---|---|---|
--endpoint-id | string | Yes | The webhook endpoint id (ep_…). At most 64 characters. |
Required scope: write.
Example:
koast get-webhook-secret --endpoint-id ENDPOINT_IDlist-webhook-deliveries
List webhook deliveries. GET /v1/webhooks/{endpointId}/deliveries, API reference.
koast list-webhook-deliveries --endpoint-id <endpoint-id> [flags]| Flag | Type | Required | Description |
|---|---|---|---|
--endpoint-id | string | Yes | The webhook endpoint id (ep_…). At most 64 characters. |
--cursor | string | No | Opaque cursor from the previous page's nextCursor. Omit for the first page. |
--limit | integer | No | Page size. Default 50. Minimum 1, maximum 100. |
Required scope: read. Paged. --all follows nextCursor to the end and prints one JSON line per item.
Example:
koast list-webhook-deliveries --endpoint-id ENDPOINT_IDlist-webhook-endpoints
List webhook endpoints. GET /v1/webhooks, API reference.
koast list-webhook-endpointsThis command takes no flags besides the global ones.
Required scope: read.
Example:
koast list-webhook-endpointsresend-failed-webhook-deliveries
Resend failed webhook deliveries. POST /v1/webhooks/{endpointId}/resend-failed, API reference.
koast resend-failed-webhook-deliveries --endpoint-id <endpoint-id>| Flag | Type | Required | Description |
|---|---|---|---|
--endpoint-id | string | Yes | The webhook endpoint id (ep_…). At most 64 characters. |
Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one.
Example:
koast resend-failed-webhook-deliveries --endpoint-id ENDPOINT_IDrotate-webhook-secret
Rotate webhook secret. POST /v1/webhooks/{endpointId}/rotate-secret, API reference.
koast rotate-webhook-secret --endpoint-id <endpoint-id>| Flag | Type | Required | Description |
|---|---|---|---|
--endpoint-id | string | Yes | The webhook endpoint id (ep_…). At most 64 characters. |
Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one.
Example:
koast rotate-webhook-secret --endpoint-id ENDPOINT_IDtest-webhook-endpoint
Send webhook test event. POST /v1/webhooks/{endpointId}/test, API reference.
koast test-webhook-endpoint --endpoint-id <endpoint-id>| Flag | Type | Required | Description |
|---|---|---|---|
--endpoint-id | string | Yes | The webhook endpoint id (ep_…). At most 64 characters. |
Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one.
Example:
koast test-webhook-endpoint --endpoint-id ENDPOINT_IDupdate-webhook-endpoint
Update webhook endpoint. PATCH /v1/webhooks/{endpointId}, API reference.
koast update-webhook-endpoint --endpoint-id <endpoint-id> [--json <file|->] [flags]| Flag | Type | Required | Description |
|---|---|---|---|
--endpoint-id | string | Yes | The webhook endpoint id (ep_…). At most 64 characters. |
--url | string | No | HTTPS URL Koast POSTs events to. No credentials in the URL; redirects are not followed. At most 2048 characters. |
--event-types | string, repeatable | No | Event types this endpoint receives. ping is always delivered by the test send and cannot be subscribed to. One of launch.completed, launch.failed, launch.partially_failed, ad.approved, ad.rejected, delivery.status_changed, metrics.updated, spend.day_closed. At least 1 item. |
--brand-ids | integer, repeatable | No | Only deliver events of these brands. Null delivers events of every brand in the organization. At least 1 item. |
--status | string | No | enabled also clears a disable caused by failed deliveries. One of enabled, disabled. |
Required scope: write. --json <file|-> supplies the whole body. Body flags are applied over it.
Example:
koast update-webhook-endpoint --endpoint-id ENDPOINT_ID