Webhook (Event Manager)

Qué es el Webhook

El Webhook es la vía por la que Conexia Infinity notifica a tu sistema cuando pasa algo en la telefonía. Internamente se configura como una acción del Event Manager: defines qué petición HTTP se lanza y a qué URL, y la plataforma la dispara automáticamente cuando ocurre el evento asociado.

Qué cubre y qué no

• Sí: avisarte de eventos de llamada (entrante, sonando, contestada, no contestada, colgada) con los datos de esa llamada, para que tu CRM registre actividad, dispare flujos o notifique a otros sistemas.
• No: controlar la llamada (transferir, aparcar, grabar) — eso es la Real-time API; ni consultar históricos — eso es la API Key; ni configurar la centralita — eso es el panel de administración.

Modelo: eventos y acciones

El Event Manager tiene dos piezas que se combinan:

• Evento — el disparador: «entró una llamada», «se contestó», «se colgó»… La plataforma trae un conjunto de eventos de llamada predefinidos (ver §03).
• Acción — qué hacer cuando ocurre el evento: una petición HTTP (webhook) a tu URL, con su método, cuerpo, cabeceras y autenticación (ver §05).

Asocias una o varias acciones a un evento; cuando el evento ocurre, la plataforma ejecuta esas acciones y envía los datos de la llamada a tu endpoint.

Eventos de llamada

Conjunto de disparadores de llamada predefinidos. Se activan o desactivan por tenant.

• Incoming Call — entra una llamada
• Ringing — está sonando
• Answered Call — contestada
• Unanswered Call — no contestada
• Hangup — colgada

Parámetros disponibles

Cada acción compone la petición con parámetros del sistema (datos de la llamada), que se referencian con doble llave {{parametro}} en la URL, el cuerpo o las cabeceras. La plataforma sustituye cada marcador por su valor real antes de enviar.

• call_id — identificador único de la llamada. Úsalo como clave para deduplicar y para casar el evento de contestada con el de colgada.
• caller_id / calling_name — quién llama (número y nombre). El número es lo que buscas en el CRM para el Call Popup.
• called_number — la extensión / número que recibe la llamada.
• direction — dirección de la llamada (entrante / saliente).
• duration — duración de la llamada (útil al final, en Hangup).

Configurar una acción (el webhook)

Una acción es la petición HTTP que se envía cuando salta el evento. Se define con estas secciones:

General

• Name — nombre identificativo de la acción.
• HTTP Method — GET / POST / PUT / PATCH / DELETE. POST es lo habitual para webhooks.
• URL — el endpoint de tu CRM que recibirá la petición.

Cuerpo (body)

• None — sin cuerpo
• Form-data — pares clave-valor
• x-www-form-urlencoded — cuerpo urlencoded
• Raw — tal cual (p. ej. JSON)

Query params y cabeceras

Puedes añadir pares clave-valor a la URL (query params) y cabeceras personalizadas (por ejemplo, un token de seguridad o un Content-Type concreto). En cualquiera de ellos el valor puede llevar {{parametro}}.

Autenticación

La acción puede firmar la petición para que tu endpoint verifique que viene de la plataforma:

Ejemplos completos

POST al colgar (form-urlencoded)

POST https://<TU_CRM>/telefonia/evento
Authorization: Bearer <TOKEN>
Content-Type: application/x-www-form-urlencoded

call_id={{call_id}}&direction={{direction}}&caller_id={{caller_id}}
&calling_name={{calling_name}}&called_number={{called_number}}
&duration={{duration}}&extension={{extension}}&unix_time={{unix_time}}

// la centralita sustituye cada {{...}} por el valor real antes de enviar

POST con cuerpo JSON (Raw)

POST https://<TU_CRM>/telefonia/evento
Authorization: Bearer <TOKEN>
Content-Type: application/json

{
  "call_id": "{{call_id}}",
  "direction": "{{direction}}",
  "caller_id": "{{caller_id}}",
  "calling_name": "{{calling_name}}",
  "called_number": "{{called_number}}",
  "duration": "{{duration}}",
  "extension": "{{extension}}"
}

Recibir el webhook en tu CRM

Tu endpoint es el otro extremo. Un patrón robusto:

1. Verifica la credencial (el token / Basic / API Key que configuraste) antes de procesar nada. Si no cuadra, responde 401 y descarta.
2. Deduplica por call_id. Un mismo evento puede llegar más de una vez; no crees dos actividades para la misma llamada.
3. Encola y responde rápido. Acepta el POST, mete el trabajo en una cola y devuelve 2xx enseguida; no hagas trabajo pesado dentro de la petición.
4. Casa contestada + colgada. Usa el call_id para unir el evento de Answered con el de Hangup y cerrar la actividad con su duración.

Seguridad y buenas prácticas

• Siempre HTTPS. Los datos de la llamada (números, nombres) viajan en cada POST.
• Autentica el origen. Configura la credencial (§06) y valídala en tu endpoint antes de procesar.
• Sé idempotente. Deduplica por call_id para no duplicar actividad ante reintentos o eventos fuera de orden.
• Responde rápido. Encola el trabajo y devuelve 2xx enseguida.
• Restringe por IP si puedes. Acepta solo peticiones desde la IP de la plataforma.
• No confíes ciegamente. Valida y normaliza los campos recibidos antes de usarlos.

Cómo empezar

1. Expón un endpoint HTTPS en tu CRM que acepte POST y valide una credencial.
2. Crea una acción en el Event Manager apuntando a esa URL, con el método, el cuerpo y la autenticación elegidos.
3. Asóciala a los eventos que te interesen (empieza por Incoming Call y Hangup).
4. Prueba y depura con el Activity Monitor; comprueba que tu endpoint deduplica y cierra la actividad correctamente.

¿Buscas las otras vías? Consulta las referencias de API Key y ARI y de Real-time API y Conector MCP en el índice de integraciones.