Un webhook es una forma de avisar a otro sistema que ocurrió un evento. En lugar de consultar repetidamente si cambió un pedido, un servicio puede enviar una notificación cuando se registra un cambio. La automatización empieza después: el sistema receptor debe comprobar la información y decidir qué acción corresponde.

Del evento a la acción

Imagina una empresa que recibe pagos por internet. Un proveedor notifica que cambió una transacción; el sistema de pedidos busca la referencia asociada, comprueba el estado y actualiza el registro. Si el pago está pendiente, no debe tratarse como confirmado solo porque la persona regresó a la página. Este recorrido es hipotético y debe adaptarse al proveedor y al acuerdo de cada negocio.

La documentación de Wompi para Colombia describe eventos de cambio de estado y una forma de comprobar la integridad de sus notificaciones. Otros proveedores pueden utilizar formatos y mecanismos distintos. Antes de desarrollar, consulta su documentación vigente y confirma qué eventos y ambientes están disponibles.

Comprueba quién envió el mensaje

La dirección que recibe eventos puede ser conocida por terceros. El sistema debe verificar las notificaciones usando el mecanismo recomendado por el proveedor, proteger las credenciales y rechazar datos que no correspondan a la operación esperada. No basta con que la información tenga un formato parecido al correcto.

Separa las pruebas de la operación real. Acuerda qué referencias, datos y credenciales pertenecen a cada ambiente para evitar que un evento de ensayo cambie un pedido de producción. No publiques secretos en el navegador, capturas o mensajes.

Diseña para demoras y repeticiones

Una notificación puede demorarse, repetirse o llegar cuando el sistema receptor no está disponible. Por eso conviene identificar cada evento o transacción y definir qué debe ocurrir si se procesa dos veces. También hay que contemplar estados anteriores, correcciones y un proceso para revisar diferencias con la fuente de pago.

Por ejemplo, emitir dos entradas por una misma compra no es el resultado deseado de recibir dos avisos iguales. La regla y su comprobación deben formar parte del alcance y las pruebas; una palabra técnica como «idempotencia» no sustituye esa decisión.

Lista para acordar una integración

  • ¿Qué evento activa el flujo y qué estado representa?
  • ¿Cómo se valida la procedencia y se protege el secreto?
  • ¿Qué referencia une el mensaje con el registro interno?
  • ¿Qué sucede ante una repetición, demora o dato faltante?
  • ¿Quién recibe una alerta y puede resolver la incidencia?
  • ¿Cómo se prueban situaciones normales y fallidas sin usar datos reales?

Un webhook puede evitar consultas manuales, pero si el proveedor no ofrece notificaciones para el cambio que necesitas, habrá que estudiar otra alternativa. Una integración fiable requiere reglas de negocio, pruebas y supervisión además del mensaje.

Acuerda cómo se investigará una diferencia

Un panel que dice «error» resulta más útil cuando conserva una referencia no sensible, el momento del intento y la etapa que falló. Define quién puede revisar esa información y cómo consultar la transacción en la fuente autorizada. Evita almacenar el contenido completo si incluye datos que no necesitas para resolver el incidente.

Incluye una prueba en la que la notificación no llega y otra en la que llega dos veces. El equipo debe poder explicar cómo detectaría la diferencia y cómo recuperaría el proceso sin repetir una acción irreversible.

Fuentes consultadas

Conectemos tu proceso con sus eventos

Explícanos qué cambio necesitas recibir y qué decisión debería activar en tu operación.

Conversar sobre un flujo