Webhooks

Scope: webhooks:manage

Registra y gestiona URLs para recibir notificaciones HTTP cuando un comprobante cambia de estado. Los webhooks se disparan para todos los documentos de la empresa.

Eventos disponibles

Evento	Cuándo se dispara
`document.authorized`	El SRI autoriza el comprobante.
`document.rejected`	El SRI rechaza el comprobante.
`document.error`	Error de sistema al procesar (red, certificado, etc.).

POST /v1/webhooks/endpoints — Registrar endpoint

Campo	Tipo	Obligatorio	Descripción
`url`	string	Sí	URL a la que se enviará el POST. Máx. 2048 chars.
`events`	array	Sí	Al menos 1: `document.authorized`, `document.rejected`, `document.error`.
`secret`	string	No	Secret para firmar el payload (HMAC-SHA256). Header `X-Webhook-Signature: sha256=<firma>`.
`description`	string	No	Descripción interna. Máx. 255 chars.

Errores: 400 EVENTS_REQUIRED, INVALID_EVENTS · 401 INVALID_API_KEY.

GET /v1/webhooks/endpoints — Listar

Lista los endpoints de la empresa. El campo secret nunca se devuelve.

GET /v1/webhooks/endpoints/:id — Detalle

Mismo objeto que en el listado. 404 WEBHOOK_ENDPOINT_NOT_FOUND.

PATCH /v1/webhooks/endpoints/:id — Actualizar

Campos opcionales: url, events, secret (o null para eliminar firma), description, active (false para pausar).

Errores: 400 INVALID_EVENTS · 404 WEBHOOK_ENDPOINT_NOT_FOUND.

DELETE /v1/webhooks/endpoints/:id — Eliminar

Elimina permanentemente el endpoint. Respuesta 200: { "success": true, "data": null }.

Formato del payload de notificación

La API envía un POST a la URL registrada con un body como:

{
  "event": "document.authorized",
  "deliveryId": "uuid-de-entrega",
  "timestamp": "2026-03-08T20:00:05.000Z",
  "data": {
    "documentId": "uuid",
    "accessKey": "07032...",
    "documentNumber": "001-001-000000001",
    "status": "AUTHORIZED",
    "documentType": "INVOICE",
    "companyId": "uuid",
    "authorizedAt": "2026-03-08T20:00:05.000Z",
    "errorDetail": null,
    "sriResponse": { "authorizationNumber": "...", "authorizedAt": "...", "environment": "1" }
  }
}

Verificación de firma

Si el endpoint tiene secret, cada entrega incluye X-Webhook-Signature: sha256=<hmac-sha256-hex>. Verifica con HMAC-SHA256 del body y timingSafeEqual. Responde con HTTP 2xx para confirmar la entrega.