> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairoconnect.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks – Descripción

> Registro de endpoints HTTPS para recibir eventos de Kairo Shield

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

```json theme={null}
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](/docs/shield/webhooks/events), [Validación de firma](/docs/shield/webhooks/validation) y [Ejemplos por lenguaje](/docs/shield/webhooks/signature-verification).