Conecta tu sistema por webhook

Una conexión de webhook tiene dos mitades independientes. Podéis activar las dos, o solo una:

• Solo entrada: nos mandáis leads y consultáis el resultado en Calligence. No configuráis endpoint.
• Solo salida: cargáis los leads a mano en la campaña (subiendo un CSV) con una columna de identificador (external_id), y nosotros os notificamos. Un lead sin identificador no genera eventos.
• Las dos: el circuito completo, que es el caso habitual.

A diferencia de las conexiones con un CRM (GoHighLevel, Zoho CRM), aquí no leemos nada de vuestro sistema: el cuerpo que nos enviáis es el lead, y todo lo que os devolvemos viaja dentro del evento. Calligence nunca abre una conexión hacia vosotros que no sea el POST a la URL que nos habéis dado.

POST https://calligence.ai/api/connectors/webhook/<token-de-la-campaña>
Content-Type: application/json
X-Calligence-Secret: <secreto de entrada de la conexión>

{
  "id": "A-1027",
  "telefono": "+34600111222",
  "nombre": "María López",
  "curso": "Oposiciones Administrativo",
  "codigo": "OPO-ADM",
  "nivel_estudios": "Bachillerato"
}

• Una URL por campaña. La URL decide en qué campaña entra el lead, qué agente le llama y con qué cadencia. La copiáis desde la campaña en Calligence (Campañas → la campaña → Copiar).
• La cabecera X-Calligence-Secret es obligatoria y es la misma para todas las campañas de esa conexión.
• Un objeto JSON por petición. No aceptamos arrays ni lotes: si tenéis diez leads, son diez peticiones. Tampoco aceptamos application/x-www-form-urlencoded ni multipart — el cuerpo tiene que ser JSON.
• Máximo 64 KiB por petición.
• Las claves son las vuestras: nos decís cuál es cuál y lo configuramos en la conexión.

En la conexión configuramos, para cada campo que necesitamos, la clave de vuestro payload que lo contiene. Se configura una vez y vale para todas las campañas de la conexión.

Con el ejemplo de arriba, el mapeo sería phone → telefono, external_id → id, name → nombre, product_name → curso, product_code → codigo y variable_fields: {"nivel_estudios": "nivel"}. Si añadís una clave nueva a vuestro payload y no nos decís nada, con conservar campos no mapeados activo el agente la recibirá igualmente como información adicional.

Cada lead se identifica por su id dentro de la campaña — el campo que hayáis mapeado a external_id. Si nos reenviáis el mismo id antes de que lo hayamos procesado con éxito, usamos los datos nuevos (podéis corregir un teléfono así). Una vez procesado correctamente, ese id queda cerrado para esa campaña: un reenvío posterior responde 200 pero no actualiza nada, y reenviarlo con un id distinto no lo corrige: crea un lead nuevo y una llamada nueva a ese número, aunque el primero siga en curso. Para corregir un lead ya procesado, avisadnos.

• El identificador no caduca. Un reenvío del mismo id a la misma campaña la semana que viene sigue siendo el mismo lead. Es la sorpresa más habitual de esta integración: si vuestro sistema reenvía el lead cada vez que se edita, el segundo envío no hará nada.
• El mismo id en otra campaña sí es otro lead, porque cada campaña es una gestión distinta.
• Sin id, identificamos el envío por teléfono + día UTC: dos envíos del mismo número el mismo día son uno. Un reenvío otro día llega al mismo cliente y al mismo lead: no crea un lead nuevo. Y si más adelante ese teléfono nos llega con un id —en un envío, en un CSV con columna de id o desde un CRM—, el id se asigna a ese mismo cliente: no se crea un segundo cliente al que volver a llamar.
• Un cuerpo rechazado (422 o 413) se registra por su contenido: reenviar el mismo cuerpo idéntico no crea nada nuevo, mientras que un cuerpo corregido entra como un intento nuevo.

Ambos son por campaña y por día UTC, y ambos responden 429 con mensajes distintos:

• 300 leads llamables al día, por defecto — el techo de llamadas. Un lead que llega por encima de este límite no se llama, salvo que nos lo reenviéis (con el mismo id) otro día UTC. La respuesta es «Se ha alcanzado el límite diario de leads para esta campaña».
• 1.500 envíos registrados al día, por defecto: cinco veces el techo de llamadas — el tope duro. Se comprueba antes que cualquier otra cosa y protege el sistema de un bucle en el origen: por encima de él no registramos nada más. La respuesta es «Demasiadas solicitudes hoy para esta campaña». Los reenvíos idénticos, que no crean registro nuevo, no consumen este tope.

Los dos números son configuración nuestra, no vuestra: los ajustamos para toda vuestra organización o para una campaña concreta, y el tope duro siempre es cinco veces el techo de llamadas. Si vuestro volumen normal los supera, decídnoslo antes de empezar.

Hacemos POST a vuestro endpoint un objeto JSON plano y versionado, con las mismas claves para todos los eventos y null en las que no apliquen. Así escribís un parser, una vez: añadir un evento o un campo nuevo no os rompe nada.

Estas quince claves viajan siempre, en todos los eventos:

Un evento status, así de legible:

{
  "version": 1,
  "event": "status",
  "event_id": 40213,
  "sent_at": "2026-09-09T10:14:03+00:00",
  "campaign_id": 27,
  "lead_id": 5561,
  "call_id": 9182,
  "external_id": "A-1027",
  "phone": "+34600111222",
  "name": "María López",
  "note": null,
  "status": "EXITO",
  "tags": ["Calligence: Éxito"],
  "scheduled_at": null,
  "title": null
}

{"call_id":null,"campaign_id":null,"event":"ping","event_id":null,"external_id":null,"lead_id":null,"name":null,"note":null,"phone":null,"scheduled_at":null,"sent_at":"2026-09-09T10:14:03+00:00","status":null,"tags":null,"title":null,"version":1}

Si vuestro endpoint ya existe y espera otros nombres, no hace falta que lo cambiéis: configuramos en la conexión un mapeo de salida que renombra o quita claves de primer nivel. Es un renombrado, no una transformación: los valores no se tocan, no se anida nada y no se calcula nada.

Por ejemplo, un endpoint que espera {id, tags, note, expected_datetime}:

{
  "external_id":  "id",                  ← renombra
  "scheduled_at": "expected_datetime",   ← renombra
  "campaign_id":  null,                  ← no enviar
  "lead_id":      null,
  "call_id":      null,
  "sent_at":      null,
  "phone":        null,
  "name":         null,
  "status":       null,
  "title":        null
}

Con ese mapeo, vuestro endpoint recibe {version, event, event_id, id, note, tags, expected_datetime}. Dos reglas: version, event y event_id pueden renombrarse pero no quitarse (sin ellas, el cuerpo no se puede enrutar, versionar ni deduplicar), y dos campos no pueden acabar con la misma clave — uno taparía al otro sin que nadie se enterase, así que el guardado se rechaza.

Cada entrega lleva la cabecera:

X-Calligence-Signature: t=1757412843,v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

• t es el momento de la firma, en segundos Unix.
• v1 es un HMAC-SHA256 en hexadecimal minúsculas, calculado con vuestro secreto de firma sobre la cadena "<t>." + cuerpo — el valor de t, un punto, y el cuerpo en crudo.
• La etiqueta es v1 a propósito: si vuestro sistema también recibe webhooks de otros proveedores con este mismo formato, la versión os dice de quién es cada firma.

En pseudocódigo, sirva para cualquier lenguaje:

cabecera = headers["X-Calligence-Signature"]     # "t=...,v1=..."
t  = valor de "t"  en la cabecera
v1 = valor de "v1" en la cabecera

# 1) Ventana de repetición: descartad lo que venga con mucho retraso.
si abs(ahora_unix() - entero(t)) > 300:
    rechazar 401                                  # 300 s = nuestra propia tolerancia

# 2) El HMAC, sobre el cuerpo en crudo.
esperado = hex(HMAC_SHA256(clave = SECRETO_DE_FIRMA,
                           mensaje = t + "." + cuerpo_en_crudo))

# 3) Comparación en tiempo constante (nunca ==).
si no comparacion_segura(esperado, v1):
    rechazar 401

responder 200

Y en Deluge, para quien verifique dentro de Zoho:

// El cuerpo TAL CUAL llega. No uséis el mapa ya parseado.
cuerpo = crmAPIRequest.get("body");
cabecera = crmAPIRequest.get("headers").get("X-Calligence-Signature");

t  = cabecera.getSuffix("t=").getPrefix(",");
v1 = cabecera.getSuffix("v1=");

// Tercer argumento "hex": v1 viaja en hexadecimal. Sin él, Deluge
// devuelve base64 y la comparación no coincidirá nunca.
esperado = zoho.encryption.hmacsha256("<secreto de firma>", t + "." + cuerpo, "hex");

if (esperado.equalsIgnoreCase(v1))
{
  // Evento auténtico: ya podéis parsear el JSON.
}

Sobre la ventana temporal: nosotros firmamos con la hora del envío y, cuando verificamos una firma nuestra, rechazamos lo que tenga más de 5 minutos. Usad ese mismo margen salvo que vuestro reloj no esté sincronizado por NTP, en cuyo caso ampliadlo un poco antes que desactivarlo. Recordad que un reintento nuestro llega con una t y un sent_at nuevos, así que no os quedaréis fuera de ventana por un reintento.

Además de la firma, podemos enviar en cada entrega una cabecera con nombre y valor fijos — un Authorization: Bearer …, una API key propia. La guardamos cifrada junto al resto de credenciales de la conexión y no aparece en ningún sitio de la interfaz. Tiene que ser una cabecera HTTP válida, y lo comprobamos al guardarla y otra vez en cada envío: el nombre, de 1 a 64 caracteres, solo con letras sin tilde, dígitos y !#$%&'*+-.^_`|~, y que no sea —da igual en mayúsculas o minúsculas— Content-Type, Content-Length, Host, Transfer-Encoding, Connection ni X-Calligence-Signature; el valor, de 1 a 512 caracteres ASCII imprimibles (nada de saltos de línea, caracteres de control, tildes ni un espacio de no separación pegado). Una cabecera que no cumple no se guarda, y si una ya guardada no cumple, la entrega falla sin reintento. Si vuestra URL ya lleva su propia clave en la query string, tampoco hay problema: la respetamos literalmente, tal y como nos la deis. Por eso la URL de destino es en sí misma una credencial, y no la mostramos entera en Calligence ni la escribimos en ningún registro.

• Deduplicad por event_id, nunca por el cuerpo. Un reintento lleva el mismo event_id pero un sent_at y una firma distintos, así que dos cuerpos idénticos no existen y comparar cuerpos os haría procesar todo dos veces.
• Diseñad el endpoint como idempotente. Podemos entregar el mismo event_id más de una vez (un reintento que en realidad sí había llegado).
• El orden no está garantizado. Si os importa, ordenad por event_id, que es creciente.

• HTTPS obligatorio. Nada de http://.
• Un nombre de dominio público. Rechazamos localhost, los dominios internos y cualquier dirección IP literal — también las públicas: una URL de producción se escribe con su dominio. La comprobación se hace al guardar la URL y otra vez en cada envío, así que una URL editada a mano se niega a enviar en lugar de fiarse.
• Sin puerto explícito y sin usuario/contraseña en la URL (https://usuario:clave@… no vale). Si necesitáis autenticación, usad la cabecera fija.
• La query string se conserva literalmente, tal y como nos la deis.

Hay tres credenciales en juego y cada una tiene un alcance distinto. Vale la pena leer esta tabla antes de rotar nada: dos de ellas afectan a todas las campañas de la conexión.

Y una nota sobre identidades: si nos enviáis un lead sin id y su teléfono ya existía en vuestra organización de Calligence con un identificador de otro sistema (por ejemplo, porque ese cliente entró antes por un CRM), los eventos de salida llevarán ese identificador en external_id. No sobrescribimos la identidad de un cliente que ya tenía una. Si lo enviáis con id y ese teléfono pertenece a un cliente con otro identificador, se crea un cliente aparte con el vuestro. Si os encontráis un external_id que no reconocéis, comparad por phone.

¿Sigues atascado? Escríbenos y lo miramos contigo.