Webhooks inteligentes: Automatiza tu flujo de trabajo con eventos en tiempo real

Implementa webhooks firmados, reintentos y deduplicación para integraciones robustas.

Tutorial 3 Enero 2025 9 min lectura
← Volver al Blog Ver Documentación

Tipos de eventos

Los principales eventos son: factura.creada, factura.enviada, factura.rechazada y factura.aceptada.

Seguridad y firmas

// Express.js (TypeScript)
app.post('/webhooks/verifactu', rawBody(), (req, res) => {
  const signature = req.header('X-Verifactu-Signature');
  if (!verify(signature, req.rawBody)) return res.sendStatus(401);
  const event = req.body; // { eventId, type, data }
  handle(event);
  res.sendStatus(200);
});

Reintentos e idempotencia

function handle(event){
  if (alreadyProcessed(event.eventId)) return;
  try {
    process(event);
  } finally {
    markProcessed(event.eventId);
  }
}

Buenas prácticas

  • Responde 2xx sólo cuando hayas persistido el evento.
  • Usa colas para desacoplar el procesamiento.
  • Guarda la cabecera de firma y el cuerpo crudo para auditoría.

Recursos

• Probar webhooks en el Playground
• Guía de Webhooks

¿Por qué usar la Verifactu API para webhooks?

La Verifactu API ofrece seguridad de extremo a extremo con firmas criptográficas, reintentos con backoff y deduplicación. Integrar webhooks con la API Verifactu reduce latencia, mejora la consistencia de datos y elimina pooling innecesario.

Verificación de firma: ejemplo ampliado

// Node.js (Express) con cuerpo crudo
app.post('/webhooks/verifactu', rawBody(), (req, res) => {
  const signature = req.header('X-Verifactu-Signature');
  if (!verify(signature, req.rawBody)) return res.sendStatus(401);
  const event = JSON.parse(req.rawBody);
  if (alreadyProcessed(event.eventId)) return res.sendStatus(200);
  process(event);
  res.sendStatus(200);
});

Errores frecuentes

  • 401 Firma inválida: comprueba que usas el cuerpo crudo, no el ya parseado.
  • 409 Duplicado: marca los eventId procesados.
  • 5xx intermitente: aplica reintentos con backoff y DLQ.

FAQs

¿Puedo reenviar eventos perdidos?

Sí. Desde tu panel o vía soporte puedes solicitar reenvío por rango temporal.

¿Los webhooks están firmados siempre?

Sí. Verifica siempre la cabecera y conserva el payload crudo para auditoría.

Enlaces internos recomendados