Webhooks
4 min de lectura
Los webhooks conectan un agente con cualquier sistema que intercambie eventos por HTTP: automatizaciones, plataformas internas, herramientas de monitorización o aplicaciones propias. Un canal puede recibir eventos, enviar peticiones o hacer ambas cosas.
Solo recibe
Solo envía
Recibe y responde
Crear el canal
Define el sentido del canal
Configura la salida cuando corresponda
Guarda y copia la URL de entrada
Describe el evento al agente
Identificar el origen
Puedes añadir un sufijo a la URL de entrada para etiquetar eventos de distintas herramientas. Por ejemplo, una misma configuración puede recibir eventos desde rutas como /clickup, /sentry o /despliegues. Kujira conserva esa fuente para que el agente pueda interpretar de dónde procede cada evento.
La URL secreta autentica el canal por sí misma. No existe una lista de permitidos para webhooks: controla el acceso a través de la URL y, cuando el emisor lo soporte, mediante una firma HMAC.
Distinguir a cada persona
En un webhook de tipo Externo, los eventos pueden venir de clientes distintos: un CRM, una tienda o un formulario de contacto. Sin más configuración, todo lo que llega por una misma fuente es un único contacto. En la sección Contactos de la ficha del canal puedes indicar en qué campos del cuerpo están los datos de quien escribe, y cada persona tendrá su propio contacto y su propia conversación en Agent Desk.
| Campo | Para qué sirve |
|---|---|
| Rutas del id | Identifica a la persona. Es el único obligatorio: sin él, la sección está desactivada. |
| Rutas del nombre | Nombre con el que aparece el contacto. |
| Rutas del correo y Rutas del teléfono | Datos de contacto que se guardan con la persona. |
Cada ruta usa puntos para entrar en el JSON: customer.id lee el campo id dentro de customer. Puedes escribir varias rutas separadas por comas; se usa la primera que tenga valor, lo que permite recibir dos formatos de evento en el mismo canal. Como el mapeo se adapta a lo que ya envía tu sistema, no hace falta cambiar el emisor.
Antes de guardar, Probar con los últimos eventos muestra quién saldría de los cinco últimos eventos recibidos con las rutas escritas. Al editar, los campos sugieren las rutas que aparecen en el último evento.
Estas conversaciones siguen las reglas de Agent Desk: si una persona del equipo asume el contacto, el agente deja de responderle. Un evento sin id va al contacto de la fuente, como sin configuración, y lo mismo ocurre a partir de 100 personas nuevas en una hora en el mismo canal. El id admite hasta 200 caracteres y debe ser un valor simple, no un objeto. En un canal de tipo Interno, esta sección no aparece y el mapeo no se aplica.
Configura la firma de entrada
El id de cada persona sale del cuerpo del evento. Sin secreto de verificación, cualquiera que conozca la URL puede escribir en nombre de cualquier contacto. El panel lo avisa mientras el mapeo esté activo sin firma.
Firmar y verificar los eventos
Para reforzar la entrada, configura un secreto de verificación y el nombre de la cabecera que envía la firma. Con un secreto definido, cada POST debe incluir una firma HMAC-SHA256 válida calculada sobre el cuerpo sin modificar; la cabecera predeterminada es x-kujira-signature.
Kujira admite el valor hexadecimal habitual y también el prefijo sha256=. Esto permite usar proveedores que emplean cabeceras distintas, como x-plane-signature o x-hub-signature-256, sin cambiar el método de verificación.
Las peticiones salientes usan un secreto independiente. Si lo defines, Kujira firma cada POST con HMAC-SHA256 en la cabecera x-kujira-signature, para que el sistema receptor pueda comprobar que procede del canal.
Evita exponer secretos
No compartas la URL de entrada ni los secretos de firma en documentación pública, chats o repositorios. Rótalos si sospechas que se han expuesto.
Respuesta y procesamiento
De forma predeterminada, Kujira acepta el evento y devuelve una respuesta inmediata mientras el agente lo procesa en segundo plano. Si el emisor necesita recibir la respuesta del agente en la misma petición, añade ?wait=1 a la URL: Kujira espera hasta 25 segundos y, si el agente tarda más, devuelve 202 Accepted mientras el trabajo continúa. Si el contacto lo atiende una persona del equipo, la respuesta es 202 Accepted inmediata, porque el agente no va a contestar.
Con Contactos configurado, las respuestas que el agente envía a la URL de salida indican a quién van: el cuerpo incluye, junto al texto, la fuente y el id de la persona ({ "text": "…", "contact": { "source": "crm", "id": "42" } }).
Configura el filtro de eco cuando una acción del agente pueda generar otro evento hacia el mismo webhook. Indica las rutas del cuerpo que identifican al autor o los identificadores propios para que el canal descarte esa actividad y no entre en un bucle.