Webhooks

Definición y propósito

Un webhook es una llamada HTTP automática que un sistema (el emisor) envía a una URL configurada en otro sistema (el receptor) cuando ocurre un evento de interés. A diferencia del modelo clásico request-response donde el cliente pregunta y el servidor responde, en webhooks el servidor empuja la información en cuanto se produce.

Estructura típica:

1. Suscripción: el consumidor le dice al sistema origen “envíame una notificación a esta URL cuando ocurra el evento X”.
2. Evento: ocurre el cambio (factura aprobada, pedido enviado, cliente creado).
3. Notificación push: el sistema origen ejecuta un POST HTTP a la URL del consumidor con el payload del evento (típicamente JSON).
4. Respuesta: el consumidor responde 200 OK para confirmar recepción. Si no responde o devuelve error, el sistema reintenta con backoff exponencial.

Webhooks vs polling

Hasta los webhooks, la integración entre sistemas se hacía por polling: cada N minutos un cron preguntaba al sistema origen “¿hay novedades?”. El polling tiene tres problemas:

• Latencia: el evento llega con retardo medio = intervalo de polling / 2.
• Coste: la mayoría de polls devuelven “nada nuevo”, consumiendo CPU y ancho de banda inútilmente.
• Escalado: si añades 10 consumidores, multiplicas por 10 las consultas al sistema origen.

Webhooks invierten el modelo: una sola entrega, en tiempo real, solo cuando hay algo que notificar. El coste se traslada del receptor al emisor, lo que es eficiente porque el emisor ya sabe cuándo hay que notificar.

Webhooks en Business Central

Business Central soporta webhooks (también llamados change notifications) a través de su API REST. El proceso:

1. Una aplicación externa (Power Automate, una función Azure, un servicio propio) se suscribe a un endpoint vía POST a /subscriptions indicando:
   • Recurso a observar (ej. customers, salesOrders, purchaseInvoices).
   • URL callback donde recibirá las notificaciones.
   • Clave compartida para verificar autenticidad.
2. La suscripción tiene vigencia limitada (3 días por defecto). Debe renovarse antes de expirar.
3. Cuando un recurso cambia (crear, actualizar, borrar), BC envía POST al callback con metadatos del cambio.
4. El consumidor recibe el aviso, llama a la API para obtener el detalle y procesa.

Casos de uso típicos:

• Sincronización CRM ↔ BC sin polling: alta de cliente en BC dispara alta en CRM, y viceversa.
• E-commerce: pedido confirmado en BC dispara webhook que activa preparación en SGA externo.
• Aprobaciones: factura validada en BC dispara webhook que notifica a Teams o email.
• Conciliación bancaria: extracto bancario procesado dispara webhook a sistemas de tesorería.

Cómo se aplica con extensiones Davisa

Las extensiones que integran procesos externos (CRM, e-commerce, BI) utilizan webhooks como mecanismo de sincronización en tiempo real. dvdata-analysis sobre Business Central, por ejemplo, puede actualizar cubos OLAP o disparar refresco incremental de Power BI ante eventos de cierre contable mediante webhooks, en lugar de programar refrescos horarios ciegos.

Errores frecuentes

1. Olvidar renovar la suscripción. Las suscripciones de BC caducan a los 3 días. Sin renovación automática, los eventos dejan de llegar y nadie se entera hasta que algo falla en cascada.
2. No validar firma o token. Cualquiera puede mandar POST a tu URL pública. Sin firma compartida o token verificado, un atacante puede inyectar eventos falsos.
3. Procesar el webhook síncronamente. Si el procesamiento tarda 30 s, BC ve timeout y reintenta, lo que genera duplicados. El patrón correcto es responder 200 OK inmediatamente y procesar en cola asíncrona.
4. No gestionar reintentos idempotentemente. Si por error de red el receptor recibe el mismo evento dos veces, el procesamiento debe ser idempotente (no crear el mismo cliente dos veces, no duplicar pedido). Sin idempotencia, los reintentos generan duplicidad.