POST for each message, Tool Call, approval, memory read, Sub-Objective update, and error.
Use webhooks when your application needs to react to Agent work. For example, you can display a response, ask a person to approve a Tool Call, update a record, or report a failed Objective.
How webhooks work
Each delivery contains one event from an Objective’s event log. Cadenya signs the raw request body with your account’s webhook signing key. Configure webhooks on each Agent. Each Agent can send events to its own URL, so you can separate responsibilities without building a router for one shared endpoint.Configure a webhook
1
Add an endpoint to your Agent
Open your Agent in the Cadenya dashboard and set Webhook events URL to the endpoint that receives Objective events.
2
Store the signing key
Find the account signing key under Account Admin and store it as
CADENYA_WEBHOOK_SECRET in your application.One signing key covers every Agent in the account. Do not expose it in browser code or commit it to your repository.3
Receive and verify deliveries
Read the request body as raw bytes or text, then pass it and the request headers to your Cadenya SDK. The SDK checks the signature and timestamp before it parses the event.
Receive events
Install the Cadenya SDK for your language, then add a handler forPOST /webhooks/cadenya. For the TypeScript example, run npm install fastify @cadenya/cadenya. The following handlers verify each delivery and print its event type and Objective ID.
Route event types
The outertype field names the webhook event, such as objective_event.assistant_message. The event-specific payload sits under data.objectiveEvent.data, where its type field acts as the payload discriminator.
Common event groups include:
The webhook events reference documents each payload and includes handlers for TypeScript, Go, Ruby, and cURL.
Envelope and signatures
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
Headers
Cadenya signs every delivery per the Standard Webhooks specification and sends it as a
POST with a JSON body.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.
401 for an invalid signature.
Prevent duplicate work
Treatwebhook-id as an idempotency key. Store it with a unique constraint before you trigger side effects. If your application has handled the ID before, return 200 without repeating the work.
Objective metadata appears in every envelope. Set an External ID or labels when you create the Objective so your webhook handler can route the event without another API request.
Test and troubleshoot
Use Svix Playground when you want to inspect deliveries before your endpoint exists. For a local handler, expose it through a tunnel, set the tunnel URL on your Agent, then create an Objective and watch the handler logs. Cadenya records each delivery attempt. Open the Agent’s webhook deliveries in the dashboard or use List webhook deliveries to inspect:- Delivery status and attempt count
- HTTP status code and response headers
- Latency and the last attempt time
- The Objective and event that caused the delivery
Rotate the signing key
Rotate the account signing key if you suspect exposure. The rotate webhook signing key endpoint returns the new key.Use case: approve a Tool Call
Objectives call tools, and some tools need approval before they run. Webhooks let your application handle that decision out of band. Cadenya pauses the Tool Call, sends anobjective_event.tool_approval_requested event, and waits for your application to approve or deny it through the API.
The webhook payload includes the Objective ID and toolCallId. Pass both values to approve the Tool Call or deny the Tool Call. A denial can include a memo that steers the Agent toward another action.
TypeScript
Use case: receive a final result
When an Agent uses structured output, theobjective_event.finalized webhook tells your application that the result is ready. Use the Objective ID from the webhook to retrieve the Objective and read its output field.
The output matches the schema configured on the Agent. See structured output to define the schema and Get an objective to retrieve the result.