Webhooks
Registra los destinos a los que kiban llama cuando pasa algo, y aprende a verificar que la llamada salió de nosotros.
Un webhook es al revés que una api key: en lugar de que tu backend llame a kiban, kiban llama a tu servidor cuando pasa algo —por ejemplo cuando una ejecución de workfloo termina—. Así no tienes que estar preguntando cada cierto tiempo si ya hay novedades.
Los registras en Desarrolladores › Webhooks, y como las api keys, tienen lista separada para Producción y Sandbox.
Registrar un destino
- Elige el ambiente.
- Haz clic en Nuevo webhook.
- Llena los campos:
| Campo | Qué va ahí |
|---|---|
| Nombre | Para reconocerlo después, por ejemplo notificaciones ERP |
| URL de destino | La dirección de tu servidor. Tiene que ser https y pública |
| Herramientas | Cuáles pueden disparar este destino |
| Cabeceras | Opcional. Una por renglón, con el formato Nombre: valor |
- Guarda.
Sobre la URL:No aceptamos direcciones de red interna: tiene que ser un dominio que se resuelva desde internet. Si tu receptor vive en una red privada, exponlo detrás de un dominio público o de un túnel.
Sobre las cabeceras:Sirven para el auth de tu servidor: si tu endpoint pide un token, lo pones aquí y nosotros lo mandamos en cada entrega. Los valores se guardan cifrados y no se vuelven a mostrar: al editar el destino verás el campo vacío. Déjalo así para conservar las que ya tenía, o escríbelas de nuevo para reemplazarlas todas.
Hay cabeceras que no puedes usar porque las pone kiban al entregar; si eliges una de ésas, el formulario te lo dice.
El secreto de firma
Al guardar el destino se muestra, una sola vez, un secreto de firma. Cópialo en ese momento: con él compruebas que cada llamada que recibes salió realmente de kiban y no de alguien más.
Cómo verificar que la llamada salió de kiban
Cada entrega llega con estas cabeceras:
| Cabecera | Qué trae |
|---|---|
X-Kiban-Signature | La firma del cuerpo, como sha256=<hex> |
| Timestamp | El momento en que se firmó, en segundos Unix. Entra en el cálculo |
| Tipo de evento | Por ejemplo workfloo.execution.succeeded |
| Herramienta | La que originó el evento: WORKFLOO, LINK o KLIN |
| Identificador de la entrega | Se repite en los reintentos, así puedes descartar duplicados |
La firma es un HMAC-SHA256 del timestamp, un punto y el cuerpo crudo —tal como llegó, sin volver a serializarlo— usando tu secreto como llave. La pantalla te muestra el cálculo exacto y un ejemplo para copiar.
Rechaza las entregas viejas:La firma sigue siendo válida para siempre, así que además de comprobarla, descarta las entregas cuyo timestamp sea muy antiguo. Sin ese corte, alguien que capture una llamada puede reenviártela más tarde y pasaría la verificación.
Descarta duplicados por el identificador de la entrega:Los reintentos reenvían exactamente la misma entrega, con el mismo identificador. Si tu proceso no es idempotente, guarda los identificadores ya atendidos y descarta los repetidos.
Eliminar un destino (webhook)
Al eliminarlo se te pide confirmar: dejas de recibir avisos en esa dirección de inmediato. Si sólo quieres dejar de recibir una herramienta, no borres el destino: edítalo y desmarca esa herramienta.
¿Y cómo sé si llegaron?
Para eso está la pestaña Webhooks eventos: ahí ves cada aviso que te enviamos, si tu servidor lo recibió y qué contestó.
Updated 5 days ago