Webhooks

Cuando tus agentes terminan llamadas (o fallan), Ryvo te manda un evento a una URL que tú configuras. Útil para:

Actualizar el deal en tu CRM con el resultado de la llamada.
Disparar un follow-up automatizado si la llamada falló.
Loggear el resumen de cada conversación en tu data warehouse.

Configurar tu webhook

Entra a app.ryvo.so/developers.
En la sección Webhook, agrega tu URL pública (HTTPS obligatorio).
Copia el signing secret que generamos. Solo se muestra una vez — guárdalo en un secret manager. Lo necesitas para verificar la firma de cada evento.

La URL del webhook debe ser pública y aceptar peticiones POST. Si está detrás de un firewall o requiere auth, los eventos no van a llegar.

Eventos disponibles

Evento	Cuándo se dispara
`call.initiated`	Cuando disparas una llamada vía `POST /v1/calls`.
`call.completed`	Cuando termina exitosamente una llamada.
`call.failed`	Cuando una llamada termina con error o no contesta.

Por defecto recibes todos los eventos. En el futuro vas a poder filtrar por tipo desde el portal.

Shape de un evento

Todos los eventos comparten esta estructura:

{
  "id": "<uuid>",
  "type": "call.completed",
  "created_at": "2026-04-30T18:35:42.123Z",
  "data": {
    /* campos específicos por tipo de evento */
  }
}

`call.initiated`

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

`call.completed`

{
  "id": "evt_02def...",
  "type": "call.completed",
  "created_at": "2026-04-30T18:35:44.987Z",
  "data": {
    "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"
  }
}

`call.failed`

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

Headers de cada delivery

Header	Valor
`Content-Type`	`application/json`
`User-Agent`	`Ryvo-Webhook/1.0`
`X-Ryvo-Signature`	`t=<unix_secs>,v1=<hex_sha256>` — verifica esto.
`X-Ryvo-Event`	El tipo de evento (ej. `call.completed`).
`X-Ryvo-Event-Id`	UUID del evento — úsalo para idempotencia.
`X-Ryvo-Delivery`	UUID único de este intento de entrega.

Reintentos automáticos

Si tu endpoint responde con un código que no es 2xx o se cuelga más de 10 segundos, reintentamos automáticamente con backoff exponencial:

Intento	Cuándo
1	Inmediato cuando ocurre el evento.
2	5 minutos después.
3	30 minutos después.
4	2 horas después.

Después del 4to intento fallido, marcamos la entrega como exhausted y no volvemos a intentar. Puedes ver el historial en app.ryvo.so/developers.

Idempotencia del lado del receptor

Aunque hagamos retry solo en errores, un mismo evento puede llegarte 2 veces (ej. tu endpoint procesó OK pero la respuesta 200 se perdió en la red). Por eso te mandamos X-Ryvo-Event-Id: guarda los IDs procesados y descarta duplicados.

const processed = new Set() // en producción, usa Redis o tu 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)

  // ... tu lógica
  res.sendStatus(200)
})

Responde rápido

Tu endpoint debe responder 200 en menos de 10 segundos. Si necesitas hacer trabajo lento (LLM call, sync a una API externa), responde 200 inmediato y procesa async (cola, background job).

Empezar

Conceptos

Webhooks

Configurar tu webhook

Eventos disponibles

Shape de un evento

`call.initiated`

`call.completed`

`call.failed`

Headers de cada delivery

Reintentos automáticos

Idempotencia del lado del receptor

Responde rápido

Próximos pasos

Verificar firmas

Probar tu webhook

​Configurar tu webhook

​Eventos disponibles

​Shape de un evento

​call.initiated

​call.completed

​call.failed

​Headers de cada delivery

​Reintentos automáticos

​Idempotencia del lado del receptor

​Responde rápido

​Próximos pasos

Verificar firmas

Probar tu webhook

Configurar tu webhook

Eventos disponibles

Shape de un evento

`call.initiated`

`call.completed`

`call.failed`

Headers de cada delivery

Reintentos automáticos

Idempotencia del lado del receptor

Responde rápido

Próximos pasos