Los webhooks permiten que tu aplicación reciba avisos del servicio sin depender únicamente de consultas periódicas. En una API Verifactu, conviene diseñarlos como parte del seguimiento de operaciones: recibir un aviso, identificar a qué documento pertenece y decidir qué actualización corresponde. El receptor también necesita un plan para los eventos repetidos o inesperados.
Parte de los tipos realmente disponibles
La referencia de nuestra API incluye operaciones para consultar tipos de webhook, configurar una URL y consultar los webhooks registrados. Revisa esas operaciones antes de diseñar tu receptor. Verifica con el equipo el formato exacto del aviso y su mecanismo de autenticación; no inventes una firma, una cabecera o una garantía de entrega que el contrato no especifique.
Relaciona cada aviso con una operación
Conserva los identificadores devueltos por los envíos y úsalos para enlazar el resultado con tu documento local. La documentación incluye consultas de envíos identificados por queueId. Esta referencia técnica debe mantenerse separada del número comercial de factura para evitar asociaciones ambiguas, especialmente si gestionas varias empresas.
Haz que repetir un aviso sea seguro
Diseña la actualización de estado para que procesar el mismo evento dos veces no duplique acciones. Comprueba el estado persistido antes de disparar correos o tareas posteriores. No presupongas que los avisos llegarán en el orden que espera tu interfaz; cuando haya dudas, contrasta la información con las consultas disponibles y evita reemplazar un resultado conocido por uno antiguo.
- Valida la autenticación y la estructura recibida.
- Comprueba a qué empresa y documento pertenece el evento.
- Registra una referencia útil para investigar incidencias.
- Ensaya duplicados, retrasos y errores temporales del receptor.
Reserva una vía de conciliación
Un webhook no elimina la necesidad de revisar operaciones cuyo estado local quedó desactualizado. Define un proceso de conciliación ajustado a los límites del servicio y una cola de incidencias para el equipo. Así podrás recuperar el seguimiento después de una interrupción sin recurrir a envíos repetidos ni a modificaciones manuales sin rastro.