POST
Add a webhook endpoint

Authorizations

Authorization
string
header
required

An API key minted in the console (ctd_…). Authenticates; never authorizes funds. A key carries scopes (read, wallets.write, transactions.write, events.write, webhooks.write, policy.write) and may be limited to vaults, to IP addresses, and in lifetime — see Authentication.

Body

application/json
url
string
required

An https:// URL with a host. One endpoint per URL in your organization.

description
string | null
event_types
enum<string>[]

The events it hears; absent or [], every event.

Available options:
operation.confirmed,
operation.failed,
operation.expired,
operation.stuck,
operation.awaiting_approval,
operation.approved,
blockchain_event.confirmed,
run.completed,
run.failed,
wallet.active,
wallet.failed

Response

Added. The answer carries the signing secret, once.

The endpoint and its signing secret, shown in this answer only.

id
string<uuid>
required
url
string
required

Where Citadel posts. An https:// URL with a host.

description
string | null
required

What the endpoint is for — your words.

event_types
enum<string>[]
required

The events it hears. [] hears every event.

Available options:
operation.confirmed,
operation.failed,
operation.expired,
operation.stuck,
operation.awaiting_approval,
operation.approved,
blockchain_event.confirmed,
run.completed,
run.failed,
wallet.active,
wallet.failed
state
enum<string>
required

active receives its events. paused: you paused it. disabled: Citadel turned it off after 5 deliveries in a row exhausted their attempts. Neither of the last two gets a delivery, not even a later one: PATCH with state: active resumes it.

Available options:
active,
paused,
disabled
disabled_at
string<date-time> | null
required

When it was paused or disabled; null while active.

consecutive_failures
integer
required

Deliveries in a row that exhausted their attempts. At 5 the endpoint is disabled; a delivered one, or a resume, sets it back to 0.

previous_secret_expires_at
string<date-time> | null
required

While a rotated secret still signs next to the new one, until when; else null.

created_at
string<date-time>
required
updated_at
string<date-time>
required
secret
string
required

The signing secret (whsec_…). Citadel shows it here only — store it now.