Webhooks

Los webhooks permiten que SIP Caller notifique a tus sistemas en tiempo real cuando sucede algo en tu cuenta, como la activación de una campaña o la finalización de una llamada. En lugar de consultar periódicamente la API REST para buscar cambios, tu aplicación expone un endpoint HTTPS, y SIP Caller le envía una solicitud HTTP POST con un payload JSON cada vez que ocurre un evento al que está suscrito.

Para comenzar a recibir webhooks, crea un webhook en la consola web, selecciona los eventos que te interesan y asígnalo a tus campañas. Consulta Webhooks para ver una guía paso a paso.

Payload del evento

Cada solicitud de webhook tiene un cuerpo JSON con la misma estructura, donde el campo data contiene los detalles del evento:

{
  "id": "01928321-9129-7f25-8ad3-80c57b16d3ed",
  "object": "event",
  "apiVersion": 2,
  "createdAt": "2024-10-12T23:47:48.133",
  "type": "CampaignActivated",
  "data": {
    ...
  }
}

Campo	Descripción
id	Identificador único del evento. Si el mismo evento se entrega más de una vez (por ejemplo, después de un reintento), conserva el mismo id, por lo que puedes usarlo para descartar duplicados.
object	Siempre event.
apiVersion	Versión del formato del payload, según la configuración del webhook.
createdAt	Fecha y hora en que ocurrió el evento.
type	Tipo del evento, como CampaignActivated o CallEnded.
data	Detalles del evento. Su contenido depende del tipo de evento, como se describe en la página de cada evento.

Versiones

Cada webhook se configura con una versión de payload. Cuando SIP Caller introduce cambios en los payloads que no son retrocompatibles, los publica en una nueva versión, para que las integraciones existentes sigan recibiendo el formato que esperan. Recomendamos usar la última versión para las nuevas integraciones. La página de cada evento incluye un selector de versión que muestra el payload de cada versión.

Tipos de eventos

Evento	Tipo	Se envía cuando
Campaña Activada	CampaignActivated	Se activa una campaña.
Campaña Pausada	CampaignPaused	Se pausa una campaña activa.
Campaña Reanudada	CampaignResumed	Se reanuda una campaña pausada.
Campaña Cancelada	CampaignCanceled	Se cancela una campaña.
Campaña Finalizada	CampaignFinished	Finaliza una campaña.
Llamada Finalizada	CallEnded	Finaliza una llamada realizada por una campaña.

Verificar las firmas

Cada solicitud de webhook incluye un encabezado Sip-Caller-Signature, que te permite verificar que la solicitud fue enviada por SIP Caller y que no fue modificada:

Sip-Caller-Signature: t=1728776932,v1=df9da282f3ffe9a7d855cc11589d86d33852ee0bbc1abaacab854c7f52e6efae

El valor t es la marca de tiempo en que se firmó el evento, y el valor v1 es la firma. Para verificarla:

1. Concatena la marca de tiempo (como texto), un punto (.) y el cuerpo JSON sin procesar de la solicitud, exactamente como se recibió.
2. Calcula un HMAC con la función de hash SHA-256, usando el secreto de firma del webhook como clave y el texto concatenado como mensaje.
3. Compara el resultado, en hexadecimal, con el valor v1. Procesa el evento solo si ambos valores coinciden.

Por ejemplo, en Python:

import hashlib
import hmac

def is_valid_signature(header: str, body: bytes, secret: str) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    message = parts["t"].encode() + b"." + body
    expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Hay ejemplos completos disponibles para Python y .NET. El secreto de firma se puede regenerar desde la consola web; cuando lo hagas, actualiza tu aplicación de inmediato, ya que las firmas realizadas con el nuevo secreto no se validarán con el anterior.

Responder rápidamente

Tu endpoint debe responder con un código de estado 2xx en cuanto recibe el evento, y realizar cualquier procesamiento que lleve tiempo después (por ejemplo, en un proceso en segundo plano). Si tu endpoint no responde a tiempo, o responde con un error, SIP Caller reintenta la entrega según la configuración de tiempo de espera y reintentos del webhook. Dado que un evento se puede entregar más de una vez, haz que tu procesamiento sea idempotente usando el id del evento.