Webhooks para Facturación Electrónica en Colombia

Un sistema de facturación que consulta el estado de cada documento mediante polling al endpoint del proveedor tecnológico funciona en volúmenes bajos pero deja de escalar tan pronto el negocio crece — sea por carga sobre los servidores propios, por límites de rate del PT, o por la latencia entre emisión y notificación al cliente final. Los webhooks resuelven ese problema al invertir el sentido del control: el PT notifica al sistema del cliente cuando ocurre el evento, sin necesidad de consultar.

Esta guía explica cómo implementar webhooks correctamente en una integración de facturación electrónica en Colombia: qué eventos conviene escuchar, cómo construir el endpoint receptor con las verificaciones de seguridad necesarias, cómo manejar idempotencia y retries, y qué patrones de fallback aplicar cuando el webhook no llega o llega corrupto.

Por qué webhooks en facturación electrónica

Polling vs webhook: el costo real

En un sistema basado en polling, el cliente consulta periódicamente el estado de cada documento hasta que cambia. Con volúmenes bajos esto es manejable. Con miles de documentos diarios, el polling produce dos problemas: alto consumo de cuota de API en el lado del PT, y latencia entre el momento real del cambio de estado y el momento en que el sistema lo detecta. Un webhook elimina ambos costos: el PT empuja la notificación en el instante en que el evento ocurre.

Beneficios para arquitecturas event-driven

En una arquitectura event-driven — colas de mensajes, microservicios, workflows orquestados — el webhook encaja naturalmente como el evento de entrada del proceso downstream. Recibido el webhook, el receptor publica en su propia cola y dispara la lógica de negocio (notificar al cliente, actualizar el sistema contable, marcar el documento como cobrado). Polling, en cambio, obliga a un componente con timer y lógica de retry que no encaja con el resto de la arquitectura.

Eventos que conviene escuchar

Eventos del ciclo de vida del documento

Los eventos mínimos a configurar son cuatro: documento aprobado por la DIAN, documento rechazado por la DIAN, documento transmitido en modo contingencia, documento retransmitido tras contingencia. Cada uno dispara una acción distinta en el sistema cliente: el aprobado activa la entrega al adquiriente, el rechazado abre incidencia para corregir y reenviar, el de contingencia marca el documento como pendiente de retransmisión, y el de retransmisión cierra ese ciclo.

Eventos de error y excepciones

Adicionalmente conviene escuchar eventos de error infraestructural: fallo persistente de transmisión tras N reintentos, expiración del certificado del firmante, rate limit alcanzado en el endpoint DIAN. Estos eventos no aplican a un documento específico sino al estado operativo de la integración, pero su detección temprana evita acumular documentos pendientes sin que el equipo se entere hasta que el monitoreo de alto nivel salta.

Implementación del endpoint receptor

Endpoint público expuesto a internet

El endpoint receptor debe ser accesible públicamente desde los servidores del PT — detrás de HTTPS con certificado válido. No puede estar protegido por VPN ni por IP allowlist si el PT no expone IPs fijas. La práctica recomendada es publicarlo en un subdominio específico (por ejemplo, webhooks.empresa.com) que enruta a un servicio dedicado dimensionado para alto pico de eventos durante horarios de facturación masiva.

Verificación de firma del webhook

Como el endpoint es público, cualquier atacante podría intentar enviar webhooks falsos. La verificación de firma HMAC — que el PT calcula sobre el payload con una clave compartida y envía en un header (X-Webhook-Signature típicamente) — confirma que el evento viene del PT y no fue alterado en tránsito. El servidor debe recalcular el HMAC con la misma clave secreta y comparar; si no coincide, descartar sin procesar y registrar en log de seguridad.

Respuesta rápida y procesamiento asíncrono

El endpoint debe responder al PT con 2xx en menos de unos pocos segundos. El procesamiento real del evento (actualizar base de datos, enviar email, marcar el documento) ocurre asíncronamente en una cola interna. Si el endpoint procesa síncrono y se demora, el PT considera el webhook fallido, reintenta y duplica eventos. Patrón recomendado: validar HMAC, persistir el evento crudo en una cola, responder 200, procesar después.

Idempotencia y manejo de duplicados

Por qué los webhooks duplican

Un webhook puede llegar dos veces por varias razones: el endpoint receptor tardó en responder y el PT reintentó, el PT tuvo un fallo después de marcar el evento como enviado, o la red duplicó el paquete por un proxy intermedio. La asunción correcta del lado cliente es que cualquier webhook puede llegar al menos una vez — nunca exactamente una vez.

Patrones de idempotencia

El patrón más simple es mantener un índice de IDs de evento ya procesados con TTL de algunos días (suficiente para cubrir la ventana máxima de reintento del PT). Al recibir un webhook, verificar si el ID ya está en el índice antes de procesar. Si está, responder 200 sin procesar de nuevo. El ID debe venir en el payload del webhook (la mayoría de PTs lo incluye); si no, calcular un hash determinístico sobre los campos clave del evento.

Retries y fallback a polling

Política de retry esperada del PT

La mayoría de PTs aplican backoff exponencial al reintentar: 30 segundos, 2 minutos, 10 minutos, 1 hora, 6 horas, hasta abandonar tras 24-48 horas. Conocer la política específica del PT que se está usando permite dimensionar el índice de idempotencia y el TTL adecuados. También permite alertar internamente si un webhook lleva varios reintentos fallidos — indicio de problema en el endpoint receptor.

Fallback a polling como red de seguridad

Aunque webhooks sean el mecanismo primario, conviene tener un job programado que cada cierto tiempo (cada 30 minutos, cada hora) reconcilie el estado de los documentos pendientes contra el endpoint del PT. Esto cubre el caso en que un webhook se perdió definitivamente o el endpoint receptor estuvo caído durante la ventana de retry del PT. La reconciliación no reemplaza a los webhooks — los complementa como red de seguridad.

Para implementaciones donde el equipo prefiere apoyarse en un panel para configurar webhooks y monitorear su entrega, la documentación técnica de Alanube describe la configuración de endpoints por evento, la rotación del secret HMAC, y el panel de eventos entregados/fallidos con opción de re-entregar manualmente desde la interfaz.

Preguntas frecuentes

¿Cuál es la diferencia entre escuchar webhooks del PT y suscribirse a un webhook directo de la DIAN? La DIAN no expone webhooks públicos para terceros. Los eventos del ciclo de vida del documento (aprobado, rechazado, transmitido en contingencia) son generados por el proveedor tecnológico después de procesar la respuesta de la DIAN. Por eso, todos los webhooks que recibe una integración vienen del PT, no de la DIAN directamente. Esto tiene la ventaja de que el PT puede enriquecer el evento con datos adicionales (número de reintentos, motivo del rechazo desgranado) que la DIAN no expone tal cual.

¿Cómo puedo testear webhooks en desarrollo sin exponer mi máquina local a internet? Las herramientas estándar son ngrok, localtunnel o el equivalente de Cloudflare Tunnel: crean un túnel HTTPS desde un dominio público hacia el puerto local. El PT envía webhooks al dominio público, el túnel los reenvía a la máquina del desarrollador. Para CI/CD existen mocks de webhook (webhook.site, mockbin) que capturan eventos para validar el payload sin necesidad de procesar la lógica completa. La práctica recomendada es combinar ambos: ngrok para test interactivo, mocks para tests automatizados.

¿Qué diferencia hay entre HMAC con SHA-256 y otros mecanismos de firma de webhooks? HMAC-SHA256 es el estándar de facto para firmar webhooks: el PT calcula HMAC(secret, payload) y envía el resultado en un header; el receptor verifica recalculando. Otros mecanismos como mTLS (mutual TLS) son más seguros pero implican mayor complejidad operativa (certificados emitidos por cada cliente). JWT también se usa en algunos casos pero añade payload sobre payload — menos eficiente que HMAC. Para integraciones de facturación electrónica colombiana, HMAC-SHA256 es lo estándar y suficiente operativamente si el secret se rota periódicamente.

¿Es posible operar la integración con la DIAN sin webhooks en absoluto? Sí. Para volúmenes pequeños — hasta unos cientos de documentos diarios — polling funciona razonablemente bien si el intervalo se ajusta al patrón de la operación. La integración consulta cada N minutos el estado de los documentos pendientes hasta que cambian. La desventaja es la latencia hasta que el sistema detecta el cambio y el consumo de cuota de API. Para volúmenes mayores o cuando la latencia importa (por ejemplo, notificar al cliente final que su factura ya tiene validez legal), los webhooks dejan de ser opcionales.

Webhooks para Facturación Electrónica en Colombia: Implementación y Arquitectura