Webhooks

SIP Caller puede activar webhooks para notificar a sistemas externos sobre eventos que ocurren en nuestra plataforma. De esta manera, se pueden desarrollar muchas integraciones personalizadas útiles entre SIP Caller y otros sistemas. Los webhooks requieren la edición Enterprise.
El procedimiento consta de 2 pasos:

1. Crear un webhook.
2. Configurar una campaña con un webhook existente.

Crear un webhook

Para crear un webhook, inicia sesión en SIP Caller y ve a Configuración > Webhooks. Luego haz clic en el botón “Crear” para abrir el cuadro de diálogo de creación de webhooks y procede de la siguiente manera:

• Ingresa un nombre descriptivo para el webhook, de modo que puedas seleccionarlo fácilmente más tarde.
• Introduce la URL que deseas que SIP Caller invoque cuando se produzcan los eventos.
• Selecciona la versión. Recomendamos usar la última versión para aprovechar las funciones más recientes, pero también puedes configurar una versión anterior por motivos de retrocompatibilidad.
• Selecciona los eventos que te interesan. Los eventos disponibles se describen en Tipos de eventos.
• Configura los ajustes avanzados según tus necesidades. Cuando creas un webhook, tienen los siguientes valores predeterminados:
  • Tiempo de Espera en Segundos: 30 segundos. El tiempo que SIP Caller espera a que tu endpoint responda.
  • Reintentos Máximos: 5. La cantidad máxima de veces que SIP Caller intenta entregar cada evento.
  • Antigüedad Máxima del Evento en Horas: 24 horas. Los eventos que esperan ser enviados durante más tiempo que este, por ejemplo mientras el webhook está deshabilitado, se descartan.
  • Máximo de Conexiones Simultáneas: 8. La cantidad máxima de solicitudes que SIP Caller envía a tu endpoint al mismo tiempo.

Tipos de eventos

Un webhook puede notificar los siguientes eventos:

• Campaña Activada: se activa una campaña, ya sea por un usuario desde la consola de SIP Caller o por una aplicación a través de la API REST.
• Campaña Pausada: se pausa una campaña activa.
• Campaña Reanudada: se vuelve a activar una campaña pausada.
• Campaña Cancelada: se cancela una campaña.
• Campaña Finalizada: finaliza una campaña.
• Llamada Terminada: finaliza una llamada realizada por una campaña, cualquiera sea su resultado.

Los eventos de campaña contienen la configuración de la campaña y, cuando el cambio fue realizado por un usuario o una aplicación, el origen del cambio. El evento Llamada Terminada contiene los detalles de la llamada: el número llamado y los valores de sus variables, los resultados de timbrado y de respuesta, las duraciones, los resultados de las interacciones con el contacto (como las entradas DTMF o los objetivos del agente de IA), los detalles de la transferencia y el resultado final de la llamada, incluyendo cuándo se volverá a intentar. Este es el evento a utilizar para actualizar tus propios sistemas, como un CRM, con el resultado de cada llamada.

Entrega y reintentos

Cada evento se envía como una solicitud HTTP POST a la URL del webhook, con un payload JSON y el encabezado “Sip-Caller-Signature”, para que tu endpoint pueda validar que la solicitud fue enviada por SIP Caller.

La entrega es exitosa cuando tu endpoint responde con un código de estado HTTP 2xx dentro del tiempo de espera configurado. Cuando el endpoint responde con cualquier otro código de estado, no responde a tiempo o no se puede acceder a él, la entrega falla y SIP Caller la reintenta automáticamente: el primer reintento se realiza 5 minutos después del intento fallido, el segundo 1 hora después, el tercero 4 horas después, y cada reintento siguiente espera 4 horas más que el anterior, hasta alcanzar los reintentos máximos. Después del último intento, el evento se marca como fallido.

Cada intento de entrega queda registrado, junto con su resultado, el código de respuesta y el tiempo de respuesta, para que puedas verificar el estado de cada evento como se describe en Resolviendo problemas con webhooks.

Configurar una campaña para disparar webhooks

Una vez creado el webhook, es necesario configurar las campañas para que lo utilicen. Para ello, solo hay que seleccionar el webhook en la pestaña Integración.

Habilitar y deshabilitar webhooks

Si encuentras un problema al procesar los webhooks disparados por SIP Caller, puedes pausar la generación de estos eventos. Al hacerlo, SIP Caller pondrá en cola estos eventos durante 24 horas, lo que te dará tiempo para corregir tu algoritmo de procesamiento de eventos y, luego, podrás habilitar los webhooks nuevamente. Para ello, ve a Configuración > Webhooks y presiona los botones “Habilitar” o “Deshabilitar” en la columna Acciones.

Regenerar el secreto de firma

Desde la columna Acciones de la lista de webhooks, también puedes hacer clic en el botón para regenerar el secreto de firma. Esto hará que SIP Caller comience a firmar los webhooks utilizando el nuevo secreto. Cualquier integración que tengas utilizando el secreto anterior dejará de funcionar, ya que la validación fallará, por lo que debes tener cuidado al realizar esta acción.

Validar la firma del webhook

Cada notificación de webhook enviada por SIP Caller tendrá el encabezado “Sip-Caller-Signature” en la solicitud HTTP, con un valor similar al siguiente:

t=1728776932,v1=df9da282f3ffe9a7d855cc11589d86d33852ee0bbc1abaacab854c7f52e6efae

El valor asignado a “t” es una marca de tiempo informando cuando el evento fue generado. El valor asignado a “v1” es la firma del webhook. Necesitarás ambos valores para hacer la verificación, de la siguiente manera:

1. Concatena la marca de tiempo (como texto), un punto (.), y los datos con formato JSON recibidos en el cuerpo de la solicitud HTTP. Por ejemplo:

   1728776932.{"id" : "01928322-860c-77f9-9c3b-7f8abe3b6afd".......}

2. Calcula la firma del webhook esperada, computando un HMAC utilizando la función de hash SHA256. Utiliza el secreto de firma del webhook como la clave, y el valor resultante de la concatenación en el punto previo como el mensaje.
3. Compara la firma del webhook calculada con el valor tomado del parámetro “v1” en el encabezado de la solicitud HTTP. Si ambos valores coinciden, entonces puedes proceder con el procesamiento del evento del webhook en forma segura.

Hemos creado ejemplos de código que muestran cómo hacer esta validación en una aplicación Python o .NET.

Resolviendo problemas con webhooks

Desde la consola de SIP Caller > Configuración > Webhooks, puedes hacer click sobre un webhook y ver todos los eventos que fueron notificados.
La lista puede ser filtrada para identificar el evento que estás buscando. Luego, cuando un evento es presionado, se abrirá un panel del lado derecho mostrando todos los detalles de cada intento de notificación.

Referencia de datos de webhooks

Los webhooks generados por SIP Caller son solicitudes HTTP POST que contienen JSON como datos, y cada solicitud incluye una versión para que podamos evolucionar el formato del payload con el tiempo sin romper las integraciones existentes. La referencia completa del JSON para cada tipo de evento y versión está disponible en la página de Referencia de datos de webhooks.