Skip to main content
ThunderPhone envía solicitudes HTTP POST a tu servidor cuando ocurren eventos durante una llamada: inicia una llamada entrante, finaliza una llamada, se completa una ejecución de evaluación, se activa una alerta, etc. Hay dos modelos de entrega:

Endpoints de webhook (recomendado)

Varias URL, secretos por endpoint, filtros de eventos por endpoint y reintentos automáticos. Adminístralos mediante GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.

Webhook heredado de URL única

Una URL por organización. Incluye los eventos del ciclo de vida de las llamadas, incluidos los intercambios de configuración bloqueantes. Se administra mediante GET/PUT /v1/webhook.
Los diez tipos de eventos del catálogo de eventos se entregan mediante endpoints de webhook. Los seis eventos del ciclo de vida de las llamadas (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) también se envían al webhook heredado de URL única: si tienes una URL heredada y un endpoint coincidente, recibes el evento en ambas rutas. El comportamiento bloqueante (el intercambio de configuración de telephony.incoming / web.incoming y el despacho de herramientas en modo webhook) existe exclusivamente en la ruta heredada; cada entrega a un endpoint es una notificación enviada sin esperar respuesta.

Formato de la carga útil

Las entregas a endpoints son un objeto JSON con data, event_id y type:
event_id es único para cada evento emitido. Es idéntico entre reintentos y entre todos los endpoints que reciben el evento: úsalo para eliminar duplicados. El webhook heredado de URL única envía el mismo type y data, pero sin event_id:
En la transmisión, cada cuerpo se serializa de forma canónica: claves ordenadas alfabéticamente, sin espacios en blanco, UTF-8. Los ejemplos con formato legible en esta documentación son solo para facilitar la lectura. Consulta el Catálogo de eventos para ver la lista completa de tipos de eventos y campos de carga útil.

Verificación de firmas

Cada solicitud incluye una firma HMAC-SHA256 sobre el cuerpo sin procesar de la solicitud en el encabezado X-ThunderPhone-Signature. La clave de firma es el secret del endpoint (o el secret de webhook a nivel de tu organización para entregas heredadas).

Pasos

  1. Lee el cuerpo sin procesar de la solicitud antes de realizar cualquier análisis.
  2. Calcula hmac_sha256(secret, body).hexdigest().
  3. Compara en tiempo constante con el encabezado X-ThunderPhone-Signature.
Firmamos exactamente los bytes que transmitimos, y esos bytes son la serialización JSON canónica (claves ordenadas, separadores compactos). Por lo tanto, verificar con el cuerpo sin procesar siempre funciona; y si tu framework solo te proporciona JSON analizado, volver a serializarlo con claves ordenadas y separadores compactos produce bytes idénticos. Ambas recetas se incluyen en la guía de verificación.

Semántica de entrega

Estas semánticas se aplican a las entregas de endpoint. El webhook heredado de una sola URL realiza un único intento sincrónico sin reintentos.
Cada evento se intenta una vez de inmediato. Cualquier respuesta 2xx confirma la entrega. Ante cualquier otro resultado (distinto de 2xx, error de conexión, tiempo de espera), reintentamos 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h después del primer intento: 8 intentos durante 24 horas. Si todos los intentos fallan, la entrega se detiene y el endpoint se marca con status="failing" en endpoints de webhook. Devuelve 2xx tan pronto como la carga útil se acepte de forma duradera; procésala de forma asíncrona.
El orden de entrega se realiza según el mejor esfuerzo. En la práctica, entregamos en el orden en que se emiten los eventos, pero los reintentos pueden alterar el orden en caso de error. Siempre elimina duplicados y reconcilia mediante call_id / id de objeto.
La entrega es al menos una vez: un reintento después de una respuesta que nunca recibimos puede duplicar un evento. Cada reintento incluye el mismo event_id, así que almacena los ids procesados y omite las repeticiones. event_id también se comparte entre endpoints: dos endpoints suscritos al mismo evento reciben el mismo event_id.
Las entregas a endpoints tienen un tiempo de espera de 30 s por intento. En la ruta heredada, las solicitudes bloqueantes que controlan el comportamiento de llamadas en vivo —el intercambio de configuración telephony.incoming / web.incoming— agotan el tiempo de espera después de 10 s, pero una respuesta lenta retrasa que se conteste la llamada, así que procura responder en un par de segundos. La ejecución de herramientas en modo webhook permite 20 s.
Los webhooks salientes se originan desde el rango de IP en la nube de ThunderPhone. Si tu firewall requiere una lista de permitidos, contacta al soporte y compartiremos los rangos actuales.

Elegir entre webhooks heredados y basados en endpoints

Las integraciones nuevas deben consumir eventos mediante webhooks basados en endpoints. Conserva (o agrega) una URL heredada solo si configuras llamadas dinámicamente al momento de contestarlas o usas la ejecución de herramientas en modo webhook: esos intercambios de solicitud/respuesta solo se ejecutan en la ruta heredada.

Relacionado

Catálogo de eventos

Todos los tipos de eventos y sus cargas útiles.

Endpoints de webhook

Administra múltiples endpoints, filtros de eventos y secretos.

telephony.incoming / web.incoming

La solicitud bloqueante que tu servidor debe responder para configurar llamadas.

telephony.complete / web.complete

Carga útil posterior a la llamada con transcripción, grabación y métricas.