Webhooks – Descripción - Kairo Connect Docs

Registre una URL HTTPS pública para recibir eventos POST cuando ocurren acciones relevantes (transacción evaluada, alerta, feedback recibido).

Gestión vía API

Método	Ruta	Descripción
`POST`	`/api/v1/webhooks`	Crear webhook (devuelve `secret` una sola vez)
`GET`	`/api/v1/webhooks`	Listar webhooks
`GET`	`/api/v1/webhooks/{id}`	Detalle
`PUT`	`/api/v1/webhooks/{id}`	Actualizar URL, eventos, retry policy
`DELETE`	`/api/v1/webhooks/{id}`	Eliminar
`GET`	`/api/v1/webhooks/{id}/logs`	Historial de entregas
`POST`	`/api/v1/webhooks/{id}/test`	Payload de prueba

Autenticación: X-API-Key en todas las rutas de gestión.

Requisitos de su endpoint

HTTPS obligatorio
Responder en menos de 30 segundos
Responder 200 (u otro 2xx) al procesar correctamente
Responder 401 si la firma no es válida
Procesamiento idempotente (use X-Kairo-Delivery para detectar duplicados)

Crear webhook — ejemplo

POST {BASE_URL}/api/v1/webhooks

{
  "name": "Producción – scoring",
  "url": "https://api.su-fintech.com/webhooks/kairo-shield",
  "events": ["transaction.scored", "transaction.high_risk", "feedback.received"],
  "description": "Eventos de fraude en producción"
}

La respuesta 201 incluye el campo secret solo en la creación. Guárdelo de forma segura; no se vuelve a mostrar. Consulte Eventos, Validación de firma y Ejemplos por lenguaje.