Webhooks

Descripcion

Crea un endpoint de webhook y suscripciones de eventos.

Endpoint

• Metodo: POST
• Path: /api/v1/webhooks

Query params

• idEmpresa (int, opcional si existe empresa en sesion)

Body

• url (string, requerido)
• events (array, requerido)
• enabled (bool, opcional)
• name (string, opcional)
• secret (string, recomendado para entrega firmada)
• headers (object, opcional)

Comportamiento de alta

• Si enabled=true, el endpoint queda ACTIVO.
• Si enabled no se envia (o false), el endpoint queda PAUSADO.
• En alta via API, se configuran defaults:
  • TimeoutSeg=10
  • RetriesMax=8
  • VersionCabecera=v1

Eventos soportados (consumo)

• OrdenDeVenta.Creada
• OrdenDeVenta.Actualizada
• OrdenDeVenta.Cancelada
• OrdenDeVenta.Finalizada
• Cfe.Emitido
• Cfe.Recibido
• contract.status.changed

Headers de entrega (salientes)

• Content-Type: application/json
• X-Bluetech-Webhook-Id
• X-Bluetech-Event
• X-Bluetech-Timestamp
• X-Bluetech-Signature (HMAC v1)
• Idempotency-Key

Confirmacion y reintentos

• Exito de entrega: cualquier respuesta 2xx.
• Reintenta en: error de red/timeout, 5xx, 429.
• No reintenta en: 4xx (fallo permanente).
• Backoff progresivo: 5s, 60s, 120s, 300s, 600s, 1800s, 3600s, 7200s, 21600s.
• Al agotar intentos, el evento queda en estado AGOTADO.

Payload ejemplo

{
  "event_type": "Cfe.Emitido",
  "event_version": "1.0",
  "occurred_at": "2026-03-04T12:20:07Z",
  "company": {"rut": "215521750017"},
  "idempotency_key": "sha1:af0bf3ac1224b",
  "data": {
    "idCfe": 776523,
    "tipoCfe": 111,
    "serie": "A",
    "numero": 19452,
    "estadoDgi": "ACEPTADO"
  }
}