JavaScript
Agents
List webhook deliveries
The delivery log for an agent’s webhooks: what Cadenya sent, what your endpoint answered, and how long it took.
GET
JavaScript
When a webhook does not arrive, this endpoint tells you whether Cadenya sent it and what your endpoint said back. It settles the question of whose bug it is before you go looking.
Set
An unrecognized
Failures retry five times with exponential backoff, starting at one second and doubling to a one-minute ceiling. Each attempt gets 30 seconds to complete. Any non-2xx response is retried.
Three failures do not retry, because retrying cannot help:
Read the key from
webhookEventsUrl on an agent’s spec and every objective event for that agent is POSTed to it. Each attempt is recorded here.
Read a delivery
Each record carries the event it delivered, where it went, and what came back.webhookId is the useful one when correlating. It is the same value Cadenya sent in the webhook-id header, so a delivery here and a request in your access log can be matched exactly.
Only
WEBHOOK_DELIVERY_STATUS_COMPLETED and WEBHOOK_DELIVERY_STATUS_FAILED are ever written. The enum also declares PENDING and DISABLED, which never appear on a record.On a failed delivery, httpStatusCode, latencyMs, and attemptCount are unreliable: attemptCount is set to the maximum rather than the number of tries made, and the response fields are left at zero. Read errorMessage.Filter to the delivery you want
The list takesobjectiveId, eventType, labels, and cursor pagination.
eventType is a 400, so a typo announces itself. There is no status filter: to find failures, list and filter on the client.
How Cadenya delivers
Each event is onePOST with Content-Type: application/json and a Standard Webhooks envelope:
- The URL is unparseable, or is not
https. Cadenya refuses plain HTTP. - Your endpoint answers
410 Gone, which Cadenya reads as “stop sending.” - The signing key cannot be loaded.
Verify the signature
Every delivery carrieswebhook-id, webhook-timestamp, and webhook-signature headers, following Standard Webhooks. The signature is an HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{body}, keyed by your account signing key, not a per-agent secret.
The SDK verifies and parses in one call:
GET /v1/account (info.webhookEventsHmacSecret) and store it as a secret. Rotate it with POST /v1/account:rotateWebhookSigningKey, which returns the new key and takes effect immediately, with no overlap window. Deploy the new key to your handler before you rotate.
Streaming or webhooks
Webhooks retry, record their outcome, and survive your process restarting. Streaming does none of that, but it needs no public endpoint and shows up instantly. Use webhooks when a machine reacts. Use streaming when a person watches.Related
Webhooks
Signature verification, the payload envelope, and a full handler.
Approving a tool
The webhook that pauses an objective until a person decides.
Stream objective events
The same events, live, with no endpoint to host.
Rotate the signing key
One call, immediate effect, no overlap.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
Example:
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Example:
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"
Query Parameters
Pagination cursor from previous response
Maximum number of results to return
Optional filter by objective ID
Example:
"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"
Optional filter by event type
Available options:
OBJECTIVE_EVENT_TYPE_UNSPECIFIED, OBJECTIVE_EVENT_TYPE_USER_MESSAGE, OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED, OBJECTIVE_EVENT_TYPE_TOOL_APPROVED, OBJECTIVE_EVENT_TYPE_TOOL_DENIED, OBJECTIVE_EVENT_TYPE_TOOL_CALLED, OBJECTIVE_EVENT_TYPE_ERROR, OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE, OBJECTIVE_EVENT_TYPE_TOOL_RESULT, OBJECTIVE_EVENT_TYPE_TOOL_ERROR, OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED, OBJECTIVE_EVENT_TYPE_MEMORY_READ, OBJECTIVE_EVENT_TYPE_CANCELLED, OBJECTIVE_EVENT_TYPE_SUB_AGENT_SPAWNED, OBJECTIVE_EVENT_TYPE_SUB_AGENT_UPDATED, OBJECTIVE_EVENT_TYPE_FINALIZED, OBJECTIVE_EVENT_TYPE_NOTICE, OBJECTIVE_EVENT_TYPE_TIMED_OUT Filters by metadata labels. Comma-separated key=value pairs, e.g. "env=prod,team=ai". A resource matches only if every pair matches exactly (AND semantics).