Webhooks
Configura webhooks en Facturalo API para recibir notificaciones cuando SUNAT procesa tus comprobantes. Firma HMAC-SHA256, hasta 5 reintentos automáticos y reenvío manual.
Facturalo puede notificar a tu servidor en tiempo real cuando ocurre un evento importante. Configura una URL por entorno y tu servidor recibirá un POST con el payload del evento.
¿Qué eventos envía Facturalo via webhook?
| Evento | Descripción | Activo por defecto |
|---|---|---|
| documento.sunat.respuesta | SUNAT procesó el documento (aceptado o rechazado). | Activo |
| documento.anulado | La baja del documento fue aceptada por SUNAT. | Activo |
| documento.correo.enviado | El PDF fue enviado al correo del cliente. | Inactivo |
| documento.correo.fallido | El envío del correo al cliente falló. | Inactivo |
| guia.sunat.respuesta | SUNAT procesó la guía de remisión. | Activo |
| documento.error | Error interno al generar o enviar el documento. | Activo |
¿Cómo verificar la firma HMAC de un webhook?
Cada evento incluye el header X-Facturalo-Firma con un HMAC-SHA256 del body usando tu webhookSecret. Verifica siempre la firma antes de procesar el evento.
X-Facturalo-Firma: {hmac-sha256}¿Qué pasa si mi servidor no responde el webhook?
Si tu servidor no responde con un código 2xx (o hay timeout/error de red), Facturalo reintenta automáticamente hasta 5 veces con backoff: 30 s, 1 min, 2 min, 5 min y 10 min. El mismo id del evento se reutiliza en todos los intentos para que puedas deduplicar. Headers útiles: X-Facturalo-Evento-Id y X-Facturalo-Intento.
Si tras los 5 intentos sigue fallando, el evento queda como fallido y puedes reenviarlo manualmente con POST /webhooks/{eventoId}/reenviar. El payload reenviado es el original guardado en base de datos.
Estado del servicio
La disponibilidad de la API, docs, web, cola de webhooks y SUNAT se publica en status.facturalo.pe.