curl --request PATCH \
--url https://api.citadel.example/api/v1/webhook_endpoints/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"state": "active"
}
'{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"description": "<string>",
"event_types": [
"operation.confirmed"
],
"state": "active",
"disabled_at": "2023-11-07T05:31:56Z",
"consecutive_failures": 123,
"previous_secret_expires_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}Change a webhook endpoint
Changes what the body names, nothing else: url, description, event_types, state.
All of it or nothing — a change that is refused leaves the endpoint as it was.
state: paused stops deliveries until you resume. state: active resumes an endpoint you
paused, and one Citadel disabled after 5 deliveries in a row exhausted their attempts; it
clears that count. Failed deliveries stay failed: send them again with
POST /webhook_deliveries/retry.
A url another endpoint of yours has answers 409 endpoint_exists; one that is not an
https:// URL with a host answers 422. A field the endpoint does not take (secret,
network, …), a field sent in the query string instead of the body, or an empty body,
answers 422. Needs the webhooks.write scope. A key limited to vaults is refused with
403 vault_limited.
curl --request PATCH \
--url https://api.citadel.example/api/v1/webhook_endpoints/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"state": "active"
}
'{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"description": "<string>",
"event_types": [
"operation.confirmed"
],
"state": "active",
"disabled_at": "2023-11-07T05:31:56Z",
"consecutive_failures": 123,
"previous_secret_expires_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}Authorizations
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.
Path Parameters
The endpoint id — id in its row, endpoint.id in a delivery.
Body
Only the fields sent change.
An https:// URL with a host that no other endpoint of yours has.
null or "" clears it.
The events it hears from now on; [], every event.
operation.confirmed, operation.failed, operation.expired, operation.stuck, operation.awaiting_approval, operation.approved, blockchain_event.confirmed, run.completed, run.failed, wallet.active, wallet.failed paused stops deliveries; active resumes a paused or disabled endpoint and clears consecutive_failures.
active, paused Response
The endpoint as it now stands.
Where Citadel posts. An https:// URL with a host.
What the endpoint is for — your words.
The events it hears. [] hears every event.
operation.confirmed, operation.failed, operation.expired, operation.stuck, operation.awaiting_approval, operation.approved, blockchain_event.confirmed, run.completed, run.failed, wallet.active, wallet.failed 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.
active, paused, disabled When it was paused or disabled; null while active.
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.
While a rotated secret still signs next to the new one, until when; else null.