Webhooks | API VERTEX ERP

Concepto

Los webhooks permiten que Vertex envíe notificaciones HTTP a tu servidor cuando ocurren eventos relevantes, como la creación o anulación de una factura.

Eventos disponibles

Evento	Descripción
`invoice.created`	Se emitió una nueva factura
`invoice.paid`	Una factura fue marcada como pagada
`invoice.voided`	Una factura fue anulada
`invoice.overdue`	Una factura venció sin pago

Formato del payload

Cada notificación se envía como un POST a tu URL con este formato: ``

json
{
  "event": "invoice.created",
  "timestamp": "2026-02-15T10:30:00Z",
  "data": {
    "id": "uuid-de-la-factura",
    "internal_number": "FEL-2026-000042",
    "total_amount": 1120.00,
    "customer_name": "Empresa Demo"
  }
}



Verificación de firma

Cada request incluye un header

X-Vertex-Signature

 con la firma HMAC-SHA256 del body:


X-Vertex-Signature: sha256=abc123def456...



Para verificar la autenticidad del webhook:

javascript
const crypto = require('crypto')

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex')

  return

sha256=${expected}

 === signature
}



Reintentos

Si tu servidor no responde con un status 2xx, Vertex reintenta con backoff exponencial:

Intento 1: inmediato
Intento 2: 1 minuto
Intento 3: 5 minutos
Intento 4: 30 minutos
Intento 5: 2 horas

Después de 10 fallos consecutivos, la suscripción se desactiva automáticamente.

Buenas prácticas

Responde con 200 lo antes posible y procesa de forma asíncrona

Implementa idempotencia usando el campo id` del evento
Verifica la firma antes de procesar el payload
Configura un timeout razonable (5-10 segundos)