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.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 condata, 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:
Verificación de firmas
Cada solicitud incluye una firma HMAC-SHA256 sobre el cuerpo sin procesar de la solicitud en el encabezadoX-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
- Lee el cuerpo sin procesar de la solicitud antes de realizar cualquier análisis.
- Calcula
hmac_sha256(secret, body).hexdigest(). - Compara en tiempo constante con el encabezado
X-ThunderPhone-Signature.
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.Reintentos
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.Orden
Orden
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.Duplicados
Duplicados
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.Tiempos de espera
Tiempos de espera
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.IPs de origen
IPs de origen
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.