Saltar al contenido principal
Los webhooks envían una notificación HTTP cuando ocurre un evento en Bold. Úsalos para que un sistema de gestión, una herramienta de análisis, una automatización interna o un servicio intermedio reaccionen sin consultar la API continuamente.
Los webhooks complementan la API. Usa la API para consultar o corregir el estado final, y usa webhooks para enterarte de que algo cambió.

Qué configura una suscripción

Flujo

1

Crea el receptor

Publica una URL que acepte peticiones JSON y responda rápido. Bold acepta http y https; usa https en producción.
2

Crea la suscripción

Registra endpoint, eventName y eventVersion en Bold.
3

Procesa los datos enviados

Guarda el identificador del evento para evitar duplicados y usa la API si necesitas más datos.
4

Devuelve una respuesta correcta

Responde con un código 2xx cuando el evento se acepte para procesamiento.

Rutas de suscripción

Estas operaciones requieren rol App.Admin.
También puedes revisar suscripciones y entregas desde Webhooks en el Panel de control.

Histórico de notificaciones

Bold guarda notificaciones y sus intentos de entrega para que puedas diagnosticar fallos.
No ejecutes trabajo pesado dentro de la respuesta HTTP del webhook. Encola el evento, responde 2xx y procesa en segundo plano.

Firma del webhook

Bold firma el cuerpo JSON serializado con HMAC-SHA256 y lo envía como hexadecimal en minúsculas en la cabecera X-HMAC-Signature.

Obtener el secreto de firma

Cada organización tiene un único secreto de firma para todas sus suscripciones. Para consultarlo, entra en Panel de control, abre Webhooks y selecciona la pestaña Firma. Puedes mostrarlo o copiarlo, y guardarlo en el gestor de secretos del sistema que recibe los webhooks. También puedes obtenerlo por API con una cuenta con el rol App.Admin:

Rotar el secreto

Si crees que el secreto se ha expuesto, usa Regenerar secreto en la pestaña Firma o llama a:
La respuesta incluye el secreto nuevo. Las notificaciones siguientes se firman con él de inmediato y no hay periodo de convivencia con el anterior. Actualiza el secreto en tus integraciones justo después de rotarlo. Si alguna notificación falla mientras tanto, puedes reintentarla desde el historial.
Verifica la firma con el cuerpo sin modificar. Si parseas y vuelves a serializar el JSON antes de verificarlo, la firma puede no coincidir.