Webhooks de facturas: que tu sistema se entere en cuanto se procesa una

Preguntar cada cinco minutos «¿hay facturas nuevas?» es la peor forma de integrar nada. Te explicamos cómo funcionan los webhooks de facturas, cómo verificar la firma HMAC y qué errores evitar al montarlos.

En este artículo
  1. Polling frente a webhooks
  2. Los eventos que importan
  3. Cómo llega la notificación
  4. Verificar la firma (esto no es opcional)
  5. Responde rápido y trabaja después
  6. Qué hacemos nosotros si tu servidor falla
  7. Hazlo idempotente
  8. Errores frecuentes al montar el receptor
  9. Cuándo usar webhooks y cuándo no

Tienes la extracción de facturas funcionando y los datos salen bien. El siguiente problema es de fontanería: cómo se entera tu sistema de que hay una factura nueva lista. Hay dos maneras, y una es claramente mejor.

Polling frente a webhooks

El polling consiste en preguntar cada X minutos: tu script llama a la API, pide la lista de facturas y compara con lo que ya tenía. Funciona, pero tiene tres inconvenientes: gastas llamadas para nada el 95 % de las veces, introduces un retraso igual al intervalo y tienes que llevar tú la cuenta de qué ya procesaste.

Un webhook le da la vuelta: en lugar de preguntar tú, el servicio te avisa. Registras una URL tuya y, cada vez que ocurre algo, recibes un POST con los datos del evento. Cero llamadas en vacío y aviso inmediato.

Los eventos que importan

  • invoice.completed — una factura terminó de procesarse y sus datos están disponibles. Es el que usarás el 90 % de las veces.
  • invoice.failed — el procesamiento falló (archivo ilegible, formato no soportado, un problema puntual). Suscribirte a este evento es lo que evita que una factura se pierda en silencio.
  • invoice.deleted — una factura se borró desde el panel o la API. Útil si replicas los datos en tu ERP y no quieres quedarte con registros huérfanos.

Los eventos se disparan procese quien procese la factura: da igual que llegue por la API, desde el panel o por email a tu buzón.

En InvoiceData das de alta cada webhook con su URL, los eventos a los que se suscribe y una descripción, y puedes activarlo o desactivarlo sin borrarlo. Cada intento de entrega queda registrado con su código de respuesta, así que puedes ver qué pasó y reintentar una entrega concreta si tu servidor estaba caído.

Cómo llega la notificación

La petición es un POST con el cuerpo en JSON y tres cabeceras propias:

POST https://tu-servidor.com/hooks/facturas
Content-Type: application/json
X-Invoice-Event: invoice.completed
X-Invoice-Timestamp: 1790000000
X-Invoice-Signature: sha256=8f4c...

{
  "event": "invoice.completed",
  "id": 1234,
  "status": "completed",
  "document_type": "factura",
  "filename": "factura-0341.pdf",
  "vendor_name": "Suministros Ebro SL",
  "vendor_tax_id": "B50123456",
  "invoice_number": "2026/0341",
  "invoice_date": "2026-09-30",
  "subtotal": 1000.00,
  "tax_amount": 210.00,
  "total": 1210.00,
  "currency": "EUR"
}

Los campos que no se hayan podido extraer llegan como null, y en un invoice.failed llegan casi todos: lo que te interesa ahí son id, filename y status. Podemos añadir campos nuevos al payload en el futuro, así que no des por hecho que la lista es fija: lee las claves que necesites e ignora el resto.

Verificar la firma (esto no es opcional)

Tu URL es pública: cualquiera que la descubra puede enviarle un POST inventado. Por eso cada entrega va firmada. Al crear el webhook recibes un secreto; la firma es un HMAC-SHA256 calculado sobre el timestamp, un punto y el cuerpo exacto de la petición, usando ese secreto como clave.

En Python, con el cuerpo sin parsear (importante: firma sobre los bytes originales, no sobre el JSON reserializado):

import hmac, hashlib

def firma_valida(secreto, timestamp, cuerpo_bytes, cabecera):
    base = (timestamp + ".").encode() + cuerpo_bytes
    esperada = hmac.new(secreto.encode(), base, hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + esperada, cabecera)

En Node:

const crypto = require('crypto');

function firmaValida(secreto, timestamp, cuerpoBuffer, cabecera) {
  const base = Buffer.concat([Buffer.from(timestamp + '.'), cuerpoBuffer]);
  const esperada = crypto.createHmac('sha256', secreto).update(base).digest('hex');
  const a = Buffer.from('sha256=' + esperada);
  const b = Buffer.from(cabecera || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Dos detalles que fallan siempre: comparar con comparación en tiempo constante (compare_digest o timingSafeEqual, nunca con el igual normal) y acceder al cuerpo en crudo. En Express necesitas el raw body; si dejas que el middleware de JSON lo parsee y luego lo vuelves a serializar, un espacio de diferencia tira la firma abajo.

Rechaza también los timestamps muy antiguos —más de unos minutos— para que nadie pueda reenviar una entrega capturada.

Responde rápido y trabaja después

La entrega tiene un tiempo de espera de 10 segundos. Si tu endpoint tarda más porque está insertando en el ERP, generando asientos o llamando a otra API, la entrega se marcará como fallida aunque tu proceso acabe bien.

El patrón correcto es: validar la firma, guardar el evento en una cola o una tabla, devolver 200 inmediatamente y procesar en segundo plano. Cualquier respuesta 2xx cuenta como entrega correcta; el resto queda registrado como error para que puedas reintentarlo.

Qué hacemos nosotros si tu servidor falla

Si la entrega falla por algo transitorio —un timeout, un corte de red, un 500 o un 429 tuyo— reintentamos automáticamente hasta tres veces, esperando unos segundos entre intentos. Cada intento queda registrado por separado en el historial de entregas, así que ahí ves si entró al primer intento o al tercero.

Un 4xx no se reintenta: si tu servidor responde 404 o 401, el problema no se va a arreglar solo. Para esos casos está el reintento manual desde el panel, una vez lo hayas corregido.

Dos detalles que sorprenden a quien integra: no seguimos redirecciones (si tu URL responde 301 o 302, la entrega se marca como fallida — registra directamente la URL final) y solo aceptamos https, por lo que ya se ha dicho arriba sobre datos fiscales en claro.

Hazlo idempotente

Un webhook puede llegarte dos veces: por un reintento manual, por un corte de red justo al responder o por un despliegue a medias. Si cada entrega crea un asiento contable, el día que se duplique tendrás un problema difícil de encontrar.

La solución es de una línea: guarda el identificador de la factura junto con tu registro y, antes de insertar, comprueba si ya lo tienes. Si ya está, responde 200 y no hagas nada más.

Errores frecuentes al montar el receptor

  • URL sin HTTPS. Estás recibiendo datos fiscales de tus proveedores; que viajen cifrados no es negociable.
  • Devolver 500 por un dato raro. Si una factura viene sin número, no revientes: guarda el evento y márcalo para revisión.
  • No mirar nunca el historial de entregas. Un webhook que lleva dos semanas devolviendo 404 porque cambiaste la ruta es una fuga silenciosa de facturas.
  • Suscribirse solo a invoice.completed. Sin el evento de fallo, las facturas que no se procesan desaparecen de tu radar.

Cuándo usar webhooks y cuándo no

Si tienes un servidor propio con una URL accesible desde internet, los webhooks son la mejor opción. Si no lo tienes, hay alternativas perfectamente válidas: montar el flujo en n8n o llamar a la API desde un proceso programado, o directamente recibir las facturas por email y exportar los datos cuando los necesites.

Para el resto de la integración —autenticación, endpoints y campos que devuelve cada respuesta— tienes el detalle en la página de la API y en la guía para desarrolladores. Si lo que quieres es que los datos acaben en tu programa de contabilidad, mira también cómo conectar la extracción con Holded, Sage o A3.

¿Quieres que lo veamos sobre tu caso concreto? Pide una demo y lo repasamos con tu flujo real delante.