Skip to main content
Un webhook es un suscriptor: una URL de callback, un secreto de firma y un alcance (global o una cuenta). Un webhook event vincula ese suscriptor con un evento del catálogo. Las entregas se registran por suscriptor en webhook_dispatch.
Todas las llamadas siguientes requieren un bearer token cuyo usuario tenga el permiso webhook:* / webhook-event:* correspondiente. En el primer release esos permisos se conceden únicamente al rol administrator.

​
1. Crear el webhook

La respuesta es la fila pública del webhook más secret, devuelto una sola vez:
secret no vuelve a devolverse: GET, listado, actualización y exportación lo omiten. Guárdalo de inmediato en tu gestor de secretos. Si se pierde, usa rotate-secret.

​
2. Elegir eventos

Busca los ids del catálogo que necesitas y reemplaza el conjunto de suscripciones en una sola llamada. El cuerpo es la lista completa deseada — los eventos que no aparezcan se dan de baja (borrado lógico), los ya presentes se conservan y los nuevos se insertan.
events debe contener al menos un id. webhook.test se mantiene siempre en el conjunto (create y el replace-set lo anteponen) para que la acción Probar tenga una suscripción contra la que registrar.
Los webhooks por cuenta solo reciben eventos con account_scope igual a account y cuyo propietario resuelto coincide. Suscribir un webhook por cuenta a un evento none (p. ej. general.address.updated) está permitido pero nunca se disparará — usa un webhook global para esos casos.

​
3. Activar y desactivar

Los webhooks se crean activos. Cambia el estado con:
Los webhooks inactivos se omiten al enrutar (no se escriben filas de dispatch para ellos). Activar un webhook también limpia consecutive_failures, disabled_at y disabled_reason, que es la forma de recuperar un suscriptor desactivado automáticamente — ver Reintentos y fallos.

​
4. Rotar el secreto

Devuelve la fila pública más el nuevo secret, de nuevo una sola vez. No hay ventana de solape: toda entrega firmada tras la llamada usa el nuevo valor. Despliega antes el secreto en tu lado, o espera una breve ráfaga de respuestas 401 que la plataforma reintentará según el backoff.

​
5. Actualizar o eliminar

  • PATCH /api/v3/webhook/webhook/{id} — actualización parcial de url, name, description, is_global, account. Se aplican de nuevo las reglas de URL.
  • DELETE /api/v3/webhook/webhook/{id} — borrado lógico; el libro mayor se conserva.
  • DELETE /api/v3/webhook/webhook/{id}/purge — borrado físico.

​
Desde Horizon Enterprise

Los mismos flujos están disponibles en Webhooks dentro de Horizon Enterprise (rol administrator): el formulario muestra el secreto en un aviso de un solo uso tras crear y rotar, el selector de eventos agrupa el catálogo por dominio y la pantalla de detalle lista las entregas con filtros, last_error y una acción Reenviar.