Webhooks

When your agents finish calls (or fail them), Ryvo sends an event to a URL you configure. Useful for:

Updating the deal in your CRM with the outcome of the call.
Triggering an automated follow-up if the call failed.
Logging the summary of every conversation in your data warehouse.

Set up your webhook

Go to app.ryvo.so/developers.
In the Webhook section, add your public URL (HTTPS required).
Copy the signing secret we generate. It is shown only once: store it in a secret manager. You need it to verify the signature of every event.

The webhook URL has to be public and accept POST requests. If it sits behind a firewall or requires auth, the events will not get through.

Available events

Event	When it fires	Lane
`conversation.started`	When a conversation starts: a call placed via `POST /v1/calls`, or a voice session of a Builder agent.	Both
`conversation.ended`	When it ends, successfully or not. Carries duration, reason and outcome.	Both
`analysis.ready`	When the post-call analysis finishes (success criteria and extracted fields).	Ryvo Engine
`call.initiated`	Alias of `conversation.started`.	Both
`call.completed`	Alias of `conversation.ended` when it ended well.	Both
`call.failed`	Alias of `conversation.ended` when it failed or went unanswered.	Both

For each occurrence you get exactly one event: the canonical one (conversation.*) if you subscribed to it, or its alias (call.*) if you did not. Never both. You pick the events of each endpoint in Developers → Webhooks, and you can change them at any time. A new endpoint starts with every event checked; the call.* names are there for endpoints already written against them.

Older subscriptions created with the * wildcard receive the call.* family only. That is on purpose: the wildcard means “everything that existed when I subscribed”, not “everything Ryvo invents later”. To receive conversation.* or analysis.ready, check them in the portal.

What changes between lanes

A Builder agent (Ryvo Engine) sends the same events with three differences, all visible in the payload:

call_id is null. When you place the call with POST /v1/calls, the id that endpoint returns is the session_id, so match on that.
session_id is included. It is the key you use to match a started with its ended, and both with the conversation.
transcript_summary is not sent: in this lane the summary is produced later by the analysis, and it travels in analysis.ready.

Engine chat does not emit conversation.* yet: a chat conversation has no end the system can observe (nobody hangs up). It does emit analysis.ready.

Shape of an event

Every event shares this structure:

{
  "id": "<uuid>",
  "type": "conversation.ended",
  "created_at": "2026-04-30T18:35:42.123Z",
  "data": {
    /* fields specific to each event type */
  }
}

Inside data, two different identifiers:

call_id: the call_… handle that POST /v1/calls returned to you. Use it to match the event with the call you triggered.
id: the identifier of the conversation in Ryvo. It is null on conversation.started because at that point the conversation does not exist yet.

`conversation.started` / `call.initiated`

{
  "id": "evt_01abc...",
  "type": "conversation.started",
  "created_at": "2026-04-30T18:32:11.123Z",
  "data": {
    "id": null,
    "call_id": "call_conv_01abcdef",
    "agent_id": "agent_8801kpabc123",
    "to": "+5215555550100",
    "metadata": {
      "lead_name": "Juan García"
    }
  }
}

`conversation.ended` / `call.completed`

{
  "id": "evt_02def...",
  "type": "conversation.ended",
  "created_at": "2026-04-30T18:35:44.987Z",
  "data": {
    "id": "7f3c2a1e-9b0d-4c6e-8a52-1d2e3f4a5b6c",
    "call_id": "call_conv_01abcdef",
    "agent_id": "agent_8801kpabc123",
    "status": "completed",
    "duration_seconds": 211,
    "transcript_summary": "El lead aceptó agendar una demo para el 5 de mayo a las 11am.",
    "termination_reason": "user_hung_up",
    "started_at": "2026-04-30T18:32:13Z",
    "ended_at": "2026-04-30T18:35:44Z"
  }
}

status can be completed, failure or unknown depending on the result of the call analysis. The summary never includes the full transcript.

`conversation.ended` / `call.failed` (could not be started)

{
  "id": "evt_03ghi...",
  "type": "call.failed",
  "created_at": "2026-04-30T18:32:25.456Z",
  "data": {
    "id": null,
    "call_id": "call_conv_01abcdef",
    "agent_id": "agent_8801kpabc123",
    "status": "failed",
    "reason": "no_answer"
  }
}

`analysis.ready`

{
  "id": "evt_04jkl...",
  "type": "analysis.ready",
  "created_at": "2026-09-21T18:41:02.000Z",
  "data": {
    "conversation_id": "7f3c2a1e-9b0d-4c6e-8a52-1d2e3f4a5b6c",
    "summary": "La clienta pidió cotización de instalación y quedó en llamar el lunes.",
    "evaluation_results": {
      "agendo_cita": { "criteria_id": "agendo_cita", "result": "failure", "rationale": "No se fijó fecha." }
    },
    "data_collection": {
      "nombre": { "data_collection_id": "nombre", "value": "Mariana López", "rationale": "Se presentó al inicio.", "json_schema": { "type": "string" } },
      "presupuesto": { "data_collection_id": "presupuesto", "value": 12000, "rationale": "Mencionó doce mil pesos.", "json_schema": { "type": "number" } }
    }
  }
}

The keys inside evaluation_results and data_collection are the identifiers you defined in the Builder (Analysis after each conversation).

Headers on every delivery

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Ryvo-Webhook/1.0`
`X-Ryvo-Signature`	`t=<unix_secs>,v1=<hex_sha256>`. Verify this one.
`X-Ryvo-Event`	The event type (for example `call.completed`).
`X-Ryvo-Event-Id`	UUID of the event. Use it for idempotency.
`X-Ryvo-Delivery`	Unique UUID of this delivery attempt.

Automatic retries

If your endpoint answers with something other than a 2xx, or hangs for more than 10 seconds, we retry automatically with exponential backoff:

Attempt	When
1	Immediately, when the event occurs.
2	5 minutes later.
3	30 minutes later.
4	2 hours later.

After the 4th failed attempt we mark the delivery as exhausted and stop trying. You can see the history in app.ryvo.so/developers.

Idempotency on the receiving side

Even though we only retry on errors, the same event can reach you twice (say your endpoint processed it fine but the 200 was lost on the network). That is why we send X-Ryvo-Event-Id: store the IDs you have processed and drop the duplicates.

const processed = new Set() // in production, use Redis or your DB

app.post("/webhook/ryvo", async (req, res) => {
  const eventId = req.headers["x-ryvo-event-id"]
  if (processed.has(eventId)) return res.sendStatus(200)
  processed.add(eventId)

  // ... your logic
  res.sendStatus(200)
})

Answer fast

Your endpoint has to answer 200 in under 10 seconds. If you need to do slow work (an LLM call, a sync to an external API), answer 200 right away and process it asynchronously (a queue, a background job).

Get started

Concepts

MCP server

Command line

Webhooks

Set up your webhook

Available events

What changes between lanes

Shape of an event

`conversation.started` / `call.initiated`

`conversation.ended` / `call.completed`

`conversation.ended` / `call.failed` (could not be started)

`analysis.ready`

Headers on every delivery

Automatic retries

Idempotency on the receiving side

Answer fast

Next steps

Verify signatures

Test your webhook

​Set up your webhook

​Available events

​What changes between lanes

​Shape of an event

​conversation.started / call.initiated

​conversation.ended / call.completed

​conversation.ended / call.failed (could not be started)

​analysis.ready

​Headers on every delivery

​Automatic retries

​Idempotency on the receiving side

​Answer fast

​Next steps

Verify signatures

Test your webhook

Set up your webhook

Available events

What changes between lanes

Shape of an event

`conversation.started` / `call.initiated`

`conversation.ended` / `call.completed`

`conversation.ended` / `call.failed` (could not be started)

`analysis.ready`

Headers on every delivery

Automatic retries

Idempotency on the receiving side

Answer fast

Next steps