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

# Introducción

> Recibe notificaciones de eventos de Bold en sistemas externos.

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.

<Info>
  Los webhooks complementan la API. Usa la API para consultar o corregir el estado final, y usa webhooks para enterarte de que algo cambió.
</Info>

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

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

## Flujo

<Steps>
  <Step title="Crea el receptor">
    Publica una URL que acepte peticiones JSON y responda rápido. Bold acepta `http` y `https`; usa `https` en producción.
  </Step>

  <Step title="Crea la suscripción">
    Registra `endpoint`, `eventName` y `eventVersion` en Bold.
  </Step>

  <Step title="Procesa los datos enviados">
    Guarda el identificador del evento para evitar duplicados y usa la API si necesitas más datos.
  </Step>

  <Step title="Devuelve una respuesta correcta">
    Responde con un código `2xx` cuando el evento se acepte para procesamiento.
  </Step>
</Steps>

## Rutas de suscripción

```http theme={null}
GET /v1/notifications/webhook/subscriptions
POST /v1/notifications/webhook/subscriptions
DELETE /v1/notifications/webhook/subscriptions/{id}
```

Estas operaciones requieren rol `App.Admin`.

<Tip>
  También puedes revisar suscripciones y entregas desde **Webhooks** en el Panel de control.
</Tip>

## Histórico de notificaciones

Bold guarda notificaciones y sus intentos de entrega para que puedas diagnosticar fallos.

```http theme={null}
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. |

<Warning>
  No ejecutes trabajo pesado dentro de la respuesta HTTP del webhook. Encola el evento, responde `2xx` y procesa en segundo plano.
</Warning>

## 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`.

```javascript theme={null}
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"),
  );
}
```

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