Skip to main content
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.

​
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.

Qué hacen los webhooks

Entregan un POST firmado segundos después del cambio, reintentan fallos transitorios con backoff exponencial y registran cada intento en un libro mayor.

Qué NO hacen

Transportar el recurso, garantizar orden ni sustituir a la API REST como fuente de verdad. Una entrega perdida nunca corrompe el estado.

​
Alcance del primer 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

1

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.
2

Catálogo de eventos

Convención de nombres, alcance por cuenta y tabla generada con todos los eventos.
3

Suscripciones

Crear un webhook, recibir el secreto de un solo uso, elegir eventos, activar y rotar.
4

Entrega y firma

Cabeceras, cuerpo y código de verificación en Node.js y Python.
5

Reintentos y fallos

Matriz de resultados, backoff, exhausted, desactivación automática y replay.
6

Operación

Sincronización del catálogo, entregas de prueba, sink, permisos y límites conocidos.
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.