Webhook events

Set a webhook URL on an agent and Cadenya POSTs one delivery per event on every objective that agent runs. Every delivery uses the same envelope and the same signature scheme, so one handler covers all of them.

Events

Event	`data.objectiveEvent.data.type`	Fires when
`objective_event.user_message`	`userMessage`	An objective receives a message from your application.
`objective_event.assistant_message`	`assistantMessage`	The model finishes a turn.
`objective_event.tool_called`	`toolCalled`	Cadenya dispatches a tool call.
`objective_event.tool_result`	`toolResult`	A tool returns.
`objective_event.tool_approval_requested`	`toolApprovalRequested`	A tool call needs a human decision.
`objective_event.tool_approved`	`toolApproved`	A reviewer approves a pending call.
`objective_event.tool_denied`	`toolDenied`	A reviewer denies a pending call.
`objective_event.tool_error`	`toolError`	A tool call fails.
`objective_event.sub_agent_spawned`	`subAgentSpawned`	An agent hands work to a sub-agent.
`objective_event.sub_agent_updated`	`subAgentUpdated`	A sub-objective changes status.
`objective_event.memory_read`	`memoryRead`	The agent loads a memory entry.
`objective_event.reasoning`	`reasoning`	The model exposes its thinking for a turn.
`objective_event.finalized`	`finalized`	The objective completes with its final result.
`objective_event.error`	`error`	The objective itself hits an error.

Envelope

Every objective event arrives in the same envelope. type names the event, data carries the agent, variation, and objective it belongs to, and data.objectiveEvent.data holds the fields documented on each event page.

Headers

Cadenya signs every delivery per the Standard Webhooks specification and sends it as a POST with a JSON body.

Header	Value
`webhook-id`	Unique per delivery. Key your idempotency on it.
`webhook-timestamp`	Unix seconds when Cadenya sent the delivery. The SDKs reject anything more than five minutes off your clock.
`webhook-signature`	`v1,` followed by a base64 HMAC-SHA256 of `id.timestamp.body`, keyed with the base64-decoded part of your `whsec_` signing key. The header can carry several space-separated signatures. One valid signature is enough.
`content-type`	`application/json`

Find the signing key under Account Admin and rotate it with rotate the webhook signing key. Cadenya records every attempt, and you can inspect them with list webhook deliveries.

Envelope fields

string

required

The event name, for example objective_event.tool_called.

string

required

RFC 3339 time when Cadenya emitted the delivery.

object

required

Everything you need to route the event without a lookup.

Show properties

object

required

Resource metadata of the agent: id, name, workspaceId, accountId, externalId, labels, profileId, createdAt, updatedAt.

object

required

Resource metadata of the variation that ran. Same shape as agent.

object

required

Operation metadata of the objective: id, workspaceId, accountId, externalId, labels, profileId, createdAt. If you set externalId when you created the objective, it comes back here, so you can route on your own ID.

object

required

The event on the objective’s timeline.

Show properties

object

required

Operation metadata of the event itself. id is the event ID (objevt_…), createdAt is when it was persisted.

object

required

The event-specific payload. type is the discriminator (toolCalled, userMessage, and so on) and the matching key holds the fields. See the Event data section of each event page.

string

required

The context window the event belongs to. Changes when compaction opens a new window.

object

Extra context, when present: objective (operation metadata) and createdBy (the profile that caused the event).

string

When the work this event records began. Present on events that measure something (an assistant turn, a tool execution), always together with duration.

string

Elapsed time as a duration string, for example "4.1s". Absent when the event is instantaneous.

Verify and unwrap

The SDKs read the signing key from CADENYA_WEBHOOK_SECRET, check the signature and timestamp, and return the typed envelope. Pass the raw request body, not a parsed and re-serialized one, because a single changed byte fails the check.

const event = await cadenya.webhooks.unwrap(rawBody, req.headers);

event, err := client.Webhooks().Unwrap(rawBody, r.Header)

event = client.unwrap_webhook(raw_body, headers)

Each event page has a full handler you can run, plus a cURL script that signs and posts a sample delivery to it.

Use the Svix Playground as a throwaway webhook URL while you shape your handler. It shows every delivery with its headers.

Overview

Tool Sets

Tools

Tool Set Secrets

Agents

Agent Variations

Agent Schedules

Objectives

Widgets

Widget Sessions

Tenants

Memory Layers

Memory Entries

Models

Uploads

Workspaces

Workspace Secrets

Workspace Admin

Accounts

API Keys

Global API Key

AI Provider Keys

Webhook events

Events

Envelope

Verify and unwrap

​Events

​Envelope

​Verify and unwrap

Events

Envelope

Verify and unwrap