Saltar al contenido principal

Endpoints de Webhook

Cada organización puede configurar múltiples endpoints para recibir notificaciones de eventos.

Campos del Endpoint​

CampoDescripción
URLDirección HTTPS que recibirá las notificaciones
DescripciónDescripción del endpoint (máx 255 caracteres)
EventosLista de tipos de eventos suscritos
SecretoClave HMAC-SHA256 para validación de firma
ActivoSi el endpoint está habilitado

Creando un Endpoint​

Al crear, el sistema genera automáticamente un secreto (whsec_...) que se muestra solo en la creación. Almacénelo de forma segura — es necesario para validar las firmas de los webhooks.

Firma de los Webhooks​

Cada entrega lleva los headers estándar Kobana (X-Kobana-App, X-Kobana-Environment, X-Kobana-Webhook-Id, X-Kobana-Event, X-Kobana-Event-Id, X-Kobana-Delivery-Id, X-Kobana-Timestamp, X-Kobana-Signature) más el trío webhook-id / webhook-timestamp / webhook-signature en el layout Standard Webhooks:

X-Kobana-Signature: v1,<base64(HMAC_SHA256(clave, delivery_id + "." + timestamp + "." + body_crudo))>

Verificación​

  1. Lee webhook-id, webhook-timestamp y webhook-signature
  2. Rechaza si el timestamp está a más de 5 minutos de tu reloj
  3. Reconstruye delivery_id.timestamp.body_crudo y calcula el HMAC-SHA256 con la clave (secret decodificado de base64 sin el prefijo whsec_)
  4. Compara con cada token v1, del header en tiempo constante

El algoritmo completo, con ejemplos en Node.js y Python, está en Referencia de la API — Webhooks. El header legado X-Signature (t=<unix>,v1=<hex>) se sigue enviando, deprecado.

Rotación de Secreto​

Cuando sospeche que el secreto fue comprometido, use la rotación de secreto. Un nuevo secreto se genera y el anterior se invalida inmediatamente.

Prueba de Webhook​

Envíe un payload de prueba para verificar si el endpoint está configurado correctamente. El resultado incluye el código HTTP y la respuesta recibida.

Desactivación Automática​

Después de 10 fallos consecutivos de entrega, el endpoint se desactiva automáticamente. Para reactivar, corrija el problema y actualice el endpoint a activo.

Protección contra SSRF​

Las URLs se validan para rechazar IPs privadas y localhost, previniendo ataques de Server-Side Request Forgery.