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

# Webhooks salientes

> Cómo horizon-api notifica a sistemas externos cuando un recurso cambia: entregas HTTPS firmadas, catálogo de eventos generado, suscripciones por cuenta o globales, reintentos y herramientas de operación.

<Info>
  Esta sección documenta la **capa de webhooks salientes** de `horizon-api`.
  Cada ruta v3 que muta datos publica un evento del catálogo; los suscriptores
  registrados en el módulo Webhook reciben un `POST` firmado por los eventos
  que eligieron. Para la dirección entrante (terceros que nos llaman, p. ej.
  proveedores de pago) consulta las secciones de cada integración.
</Info>

## Qué es

Un webhook es un endpoint HTTPS de tu propiedad. Cuando un recurso que te
interesa se crea, actualiza, activa o elimina, `horizon-api` envía una
**notificación fina y firmada** a ese endpoint. El cuerpo identifica *qué*
cambió (`event`, `data.document_id`, `data.account`), no el recurso completo:
tu sistema lee después el estado actual mediante la API REST con sus propias
credenciales.

<CardGroup cols={2}>
  <Card title="Qué hacen los webhooks" icon="bell">
    Entregan un `POST` firmado segundos después del cambio, reintentan fallos
    transitorios con backoff exponencial y registran cada intento en un
    libro mayor.
  </Card>

  <Card title="Qué NO hacen" icon="circle-xmark">
    Transportar el recurso, garantizar orden ni sustituir a la API REST como
    fuente de verdad. Una entrega perdida nunca corrompe el estado.
  </Card>
</CardGroup>

## Alcance del primer release

| Capacidad                                                           | Estado                                  |
| ------------------------------------------------------------------- | --------------------------------------- |
| Catálogo generado desde el árbol de rutas v3 (`<recurso>.<acción>`) | Disponible                              |
| Suscripciones globales (`is_global: true`) y por cuenta             | Disponible                              |
| Firma HMAC-SHA256 con marca de tiempo (`x-bbrands-signature`)       | Disponible                              |
| Reintentos `1 m → 5 m → 30 m → 2 h → 6 h`, luego `exhausted`        | Disponible                              |
| Desactivación automática tras 20 entregas fallidas consecutivas     | Disponible                              |
| Replay por operador, entrega de prueba, rotación de secreto         | Disponible                              |
| Endpoints de resumen (dashboard) y estado del catálogo              | Disponible                              |
| Payload del recurso dentro del cuerpo                               | No previsto — lee el recurso por la API |
| IP de egreso fija para listas blancas                               | No disponible en este release           |

## Requisitos del endpoint suscriptor

* **Solo HTTPS.** Las URLs `http://` se rechazan salvo en el entorno local
  `development`.
* **Host público.** Se rechazan loopback, link-local, rangos privados (IPv4 e
  IPv6), direcciones de metadatos de nube y nombres `*.internal` al crear o
  actualizar el webhook.
* **Sin redirecciones.** El worker nunca sigue `3xx`; una redirección es un
  error terminal para ese intento.
* **Responde `2xx` en menos de 10 segundos.** Procesa de forma asíncrona.
* **Verifica la firma** antes de confiar en el cuerpo y **deduplica por id de
  entrega**, porque reintentos y replays lo reutilizan.

## Cómo leer esta sección

<Steps>
  <Step title="Arquitectura">
    Las dos etapas de cola (`webhook-out-route`, `webhook-out-deliver`), el
    libro mayor `webhook_dispatch` y la regla de publicación condicionada a
    suscriptores.
  </Step>

  <Step title="Catálogo de eventos">
    Convención de nombres, alcance por cuenta y tabla generada con todos los
    eventos.
  </Step>

  <Step title="Suscripciones">
    Crear un webhook, recibir el secreto de un solo uso, elegir eventos,
    activar y rotar.
  </Step>

  <Step title="Entrega y firma">
    Cabeceras, cuerpo y código de verificación en Node.js y Python.
  </Step>

  <Step title="Reintentos y fallos">
    Matriz de resultados, backoff, `exhausted`, desactivación automática y
    replay.
  </Step>

  <Step title="Operación">
    Sincronización del catálogo, entregas de prueba, sink, permisos y límites
    conocidos.
  </Step>
</Steps>

<Note>
  Gestionar webhooks (crear, suscribir, rotar, replay) requiere el rol
  `administrator` en Horizon Enterprise o los permisos `webhook:*`
  equivalentes en un token de API. Consulta la
  [referencia API](/api-reference/webhook/webhook/find-all).
</Note>