Empezar con webhooks

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

Campo	Descripción
Evento	Nombre completo del evento que quieres recibir, por ejemplo `Planning.SalesOrder.LineConfirmed`.
Versión	Versión mayor del contrato del evento.
URL de recepción	Dirección pública donde tu sistema recibe la notificación.

{
  "endpoint": "https://integraciones.example.com/bold/webhooks",
  "eventName": "Planning.SalesOrder.LineConfirmed",
  "eventVersion": 1
}

Flujo

Crea el receptor

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

Crea la suscripción

Registra endpoint, eventName y eventVersion en Bold.

Procesa los datos enviados

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

Devuelve una respuesta correcta

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

Rutas de suscripción

GET /v1/notifications/webhook/subscriptions
POST /v1/notifications/webhook/subscriptions
DELETE /v1/notifications/webhook/subscriptions/{id}

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.

GET /v1/notifications/webhook
GET /v1/notifications/webhook/{id}
GET /v1/notifications/webhook/{id}/attempts
POST /v1/notifications/webhook/{id}/retry

Estado	Qué significa
`Pending`	La notificación está pendiente o programada para reintento.
`Success`	El receptor respondió con un código `2xx`.
`Failure`	Se agotaron los intentos automáticos. Puedes reintentar manualmente.

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.

import crypto from "node:crypto";

function isValidSignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  if (!signature || signature.length !== expected.length) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex"),
  );
}

Verifica la firma con el cuerpo sin modificar. Si parseas y vuelves a serializar el JSON antes de verificarlo, la firma puede no coincidir.

Primeros pasos

Webhooks

Referencia de API

Qué configura una suscripción

Flujo

Rutas de suscripción

Histórico de notificaciones

Firma del webhook

​Qué configura una suscripción

​Flujo

​Rutas de suscripción

​Histórico de notificaciones

​Firma del webhook

Qué configura una suscripción

Flujo

Rutas de suscripción

Histórico de notificaciones

Firma del webhook