Webhooks de Factumel: eventos, firma HMAC y reintentos
Configurá webhooks de facturación electrónica, validá HMAC, evitá duplicados y entendé eventos de documentos y respuestas de DGI.
Qué notifican los webhooks
Factumel puede enviar eventos cuando un documento se crea, firma, transmite, acepta, observa o rechaza, además de cambios relacionados con DGI e intercambio. El evento firmado se envía a un destino HTTPS público configurado y validado contra redes privadas.
Los webhooks son entregas de tipo al menos una vez: tu sistema puede recibir el mismo eventId repetido o fuera de orden. No se debe activar una segunda venta al recibir un duplicado.
Configuración desde el panel o API
Podés administrar destinos en /dashboard/webhooks o mediante /api/v1/webhooks con una clave organizacional con el scope webhooks:manage. Crear y rotar un destino devuelve su secreto HMAC sólo una vez.
Una clave restringida a una empresa no puede gestionar webhooks organizacionales, aunque tenga otros permisos fiscales.
Verificar integridad
Verificá la firma antes de interpretar el JSON, usando el cuerpo literal recibido, comparación constante y control de antigüedad del timestamp. También verificá el id del evento y guardalo bajo una restricción UNIQUE.
Respondé HTTP 2xx sólo después de persistir el evento y su resultado. Un reintento por fallo de red no es un evento fiscal nuevo.
firma = HMAC_SHA256(secret, timestamp + "." + rawBody)
Header: x-factumel-signature: v1=<hexadecimal>
Header: x-factumel-timestamp: <segundos Unix>