Webhooks

2 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

Un sistema externo hace POST a una URL única de Kujira. Es la opción habitual para notificaciones y eventos.

Solo envía

El agente publica sus respuestas o acciones en una URL externa. Requiere una URL de salida.

Recibe y responde

Combina ambos sentidos: el agente procesa eventos entrantes y puede devolver una acción al sistema de origen.

Crear el canal

Define el sentido del canal

En Canales del agente, añade un webhook y elige si recibe eventos, envía peticiones o hace ambas cosas. Los canales de solo envío necesitan una URL de salida antes de poder guardarse.

Configura la salida cuando corresponda

Añade la URL pública a la que el agente hará POST. Si el sistema externo necesita verificar el origen, define también un secreto de firma.

Guarda y copia la URL de entrada

Kujira genera una URL secreta para los eventos entrantes. Copia esa URL en el sistema que debe emitir los eventos; no se escribe manualmente en Kujira.

Describe el evento al agente

Añade instrucciones que expliquen el formato, los eventos relevantes y qué acción debe tomar el agente ante cada uno.

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.

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.

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.

Comprobar la integración

Haz una prueba mínima

Envía un POST JSON de prueba a la URL de entrada y confirma que aparece una conversación o evento para el agente. Incluye la firma si has configurado un secreto.

Si recibes 401

Revisa el secreto, la cabecera configurada y que la HMAC se calcule sobre el cuerpo original, sin reformatearlo antes de firmar.

Si el agente no puede contestar

Comprueba la URL de salida, su disponibilidad pública y la configuración de firma saliente. Un canal solo de entrada no realiza POST de respuesta.

Comprueba la salida con un clic

El botón **Probar** de la ficha del canal entrega un mensaje de prueba en tu URL de salida, firmado igual que los demás. El texto dice que es una prueba y Kujira te avisa antes de enviarlo.