Skip to main content
Webhooks in Cadenya are dispatched from an Agent’s Objective events to your application as they happen. Set one URL on the Agent, then Cadenya sends a signed 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 for POST /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.
Pass the raw request body to unwrap. Parsing the JSON and serializing it again changes the signed bytes, so verification fails even when the data looks identical.

Route event types

The outer type 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.
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.
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.
The SDK rejects a delivery when its signature does not match or its timestamp differs from your server clock by more than five minutes. Keep your server clock in sync and return 401 for an invalid signature.

Prevent duplicate work

Treat webhook-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
The response body is not retained. Put diagnostic detail in response headers or your own application logs.

Rotate the signing key

Rotate the account signing key if you suspect exposure. The rotate webhook signing key endpoint returns the new key.
Rotation invalidates the old key for every Agent in the account. Update CADENYA_WEBHOOK_SECRET in every receiver as part of the same cutover.

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 an objective_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, the objective_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.