Webhooks

Qué conseguirá

Cada vez que uno de sus agentes termine una llamada, Phynxa enviará el resumen, la transcripción y los datos de la llamada a una dirección web que usted controla. También puede avisarle cuando empieza una llamada y cada vez que se ejecuta una herramienta.

Requisitos previos

• Un punto de conexión http o https público que acepte la solicitud y responda con un estado 2xx. Se rechazan las direcciones privadas e internas.
• El rol de owner o admin.

Configuración paso a paso

1. Abra Tools y la pestaña Webhooks, y elija New webhook.
2. Escriba un Name (para su referencia, por ejemplo CRM sync) y marque los Agents que deben enviar a él. Un agente usa un webhook, así que marcar un agente que ya tenga otro lo traslada a este.
3. Elija crearlo. Se abre la página del webhook.
4. En Where to send it, elija el Method (POST por defecto) y escriba la URL, por ejemplo https://yoursite.com/hooks/calls.
5. Fije un Signing secret. Es opcional pero recomendable: le permite demostrar que cada solicitud procede de Phynxa. Consulte Verifique las firmas de los webhooks.
6. En What to send, marque las partes que quiera (consulte más abajo). En Limits fije Timeout y Attempts.
7. Elija Save changes.
8. En cada agente, active Webhook en Tools, Built-in, y elíjalo en Send to.

Qué lleva cada entrega

El nombre del evento y el id de la llamada se envían siempre. Marque cualquiera de estos para añadirlos:

Si no se marca nada, se envía todo.

Tipos de evento

Un webhook puede recibir tres eventos. Marque los que quiera en Events; Call completed viene marcado en un webhook nuevo.

Las marcas de What to send se aplican a todos los eventos, pero solo a las partes que ese evento tiene: un call.started lleva los detalles de la llamada y no tiene dónde añadir una transcripción. Un tool.called lleva siempre su bloque tool.

Cómo se comportan los eventos en vivo:

• En orden. call.started, después los tool.called que haya y después call.completed.
• Nunca estorban a quien llama. Se envían en segundo plano. Un punto de conexión lento o inaccesible no puede hacer esperar a quien llama. Si hay más de 50 eventos esperando en una llamada, se descartan los más recientes. Al terminar la llamada, Phynxa espera unos segundos a lo que esté en cola y después envía call.completed.
• Gratis si no los usa. Un agente cuyo webhook no los ha marcado no hace ningún trabajo extra durante la llamada.
• Intentos. Se aplica Attempts, pero un evento en vivo espera como máximo 5 segundos una respuesta, diga lo que diga Timeout.
• Qué llamadas. El webhook se lee cuando empieza la llamada, así que marcar un evento afecta a las llamadas que empiecen después de guardar. Un webhook en pausa no envía nada.

call.started:

{
  "event": "call.started",
  "call_id": "b130a71059eb44e3bfff982ecc035585",
  "call": {
    "id": "b130a71059eb44e3bfff982ecc035585",
    "agent_id": "230af209-7759-45af-839e-55cf5dcda8fd",
    "agent_name": "Reception Marina",
    "direction": "inbound",
    "from_number": "+971501234567",
    "to_number": "+97145551234",
    "started_at": "2026-10-12T09:14:03.120000+00:00"
  }
}

tool.called:

{
  "event": "tool.called",
  "call_id": "b130a71059eb44e3bfff982ecc035585",
  "call": {
    "id": "b130a71059eb44e3bfff982ecc035585",
    "agent_id": "230af209-7759-45af-839e-55cf5dcda8fd",
    "agent_name": "Reception Marina",
    "direction": "inbound"
  },
  "tool": { "id": "5d1f0c7a", "name": "check_order", "ok": true, "duration_ms": 420 }
}

Ejemplo de carga útil

Con todas las partes marcadas (los valores son un ejemplo):

{
  "event": "call.completed",
  "call_id": "b130a71059eb44e3bfff982ecc035585",
  "call": {
    "id": "b130a71059eb44e3bfff982ecc035585",
    "agent_id": "230af209-7759-45af-839e-55cf5dcda8fd",
    "agent_name": "Reception Marina",
    "direction": "inbound",
    "from_number": "+971501234567",
    "to_number": "+97145551234",
    "started_at": "2026-10-12T09:14:03.120000+00:00",
    "ended_at": "2026-10-12T09:15:41.880000+00:00",
    "seconds": 98.8,
    "turns": 9,
    "p50_latency_ms": 820,
    "p95_latency_ms": 1311,
    "outcome": "completed"
  },
  "review": {
    "summary": "Caller asked to book a cleaning on Thursday afternoon and was booked for 2:30 pm.",
    "intent": "book an appointment",
    "sentiment": "positive",
    "outcome": "appointment_booked",
    "score": 5,
    "status": "complete"
  },
  "transcript": [
    { "role": "assistant", "text": "Thank you for calling Acme Dental. How can I help?", "at": "2026-10-12T09:14:04+00:00" },
    { "role": "user", "text": "Hi, can I book a cleaning this Thursday?", "at": "2026-10-12T09:14:09+00:00" }
  ],
  "action_items": ["Send a reminder the day before"],
  "entities": { "name": "Sara K.", "email": "sara@example.com" }
}

Notas sobre los campos:

• direction es inbound, outbound o web (una prueba en el navegador).
• El role de la transcripción es assistant (el agente) o user (quien llama).
• review.status es complete, pending (la revisión no ha terminado) u off (Call summary está desactivado para el agente). Las demás claves conservan su forma en cualquier caso.
• outcome dentro de review es uno de resolved, needs_followup, information_given, appointment_booked, no_answer, abandoned o unclear.
• Con solo Summary marcado recibe event, call_id y review, y nada más.

Detalles de la solicitud

Phynxa envía una solicitud a su URL con estas cabeceras:

Reintentos y qué cuenta como entregado

• Entregado: su punto de conexión responde con un estado 2xx.
• Reintentado: los tiempos de espera agotados, los errores de conexión y las respuestas 5xx, hasta Attempts intentos (de 1 a 5; los webhooks nuevos empiezan en 3), con una breve pausa entre ellos.
• No se reintenta: una respuesta 4xx. Phynxa supone que su punto de conexión rechazó la solicitud y seguirá rechazándola.
• Timeout: cuánto espera Phynxa una respuesta, hasta 60 segundos (los webhooks nuevos empiezan en 10).
• No se siguen las redirecciones.

Un webhook caído nunca pierde el registro de la llamada: la llamada se guarda en History en cualquier caso.

Revisar las entregas

En Recent deliveries (los últimos 50 intentos), cada fila muestra el evento, si tuvo éxito, el código de estado, el tiempo que tardó y cualquier error. En un agente, la pestaña Logs enumera las entregas del webhook al que envía.

Prueba

En la página del webhook elija Send test. Envía un ejemplo de cada evento que marcó (el ejemplo de fin de llamada si no marcó ninguno), con solo las partes que marcó y firmado exactamente igual que uno real. Muestra el resultado y, si un ejemplo falla, indica el evento. Cada ejemplo es una fila en Recent deliveries. Guarde primero: la prueba usa la versión guardada.

Resultado esperado

Su punto de conexión recibe la solicitud, responde 2xx y la fila de Recent deliveries figura como exitosa.

Solución de problemas

Consulte Problemas de entrega de webhooks.

Guías relacionadas

• Verifique las firmas de los webhooks
• API REST