Un formulario recibe una solicitud y otra aplicación debe enterarse para iniciar el trabajo. Puedes consultar cada cierto tiempo si hay novedades o hacer que el sistema avise cuando ocurre el evento. Un webhook permite diseñar ese segundo recorrido cuando la plataforma lo ofrece.
Un webhook es un aviso que una aplicación envía a una dirección configurada cuando sucede un evento. Ese aviso contiene datos que el sistema receptor puede utilizar para iniciar una comprobación o una tarea.
El aviso no garantiza que el proceso de negocio haya terminado. Hay que comprobar que llega, que es válido y que se trata una sola vez cuando corresponde. Ahí está buena parte del trabajo de una integración fiable.
Cómo funciona un webhook con un ejemplo sencillo
Imagina un portal que permite registrar solicitudes. Cuando se crea una, envía un aviso con su identificador a la aplicación interna. El receptor verifica el mensaje, registra el evento y prepara la tarea para el equipo adecuado.
La documentación de GitHub sobre webhooks explica el mecanismo de suscripción a eventos y entrega de datos. Cada proveedor define sus eventos, formato y condiciones, por lo que ese ejemplo técnico no debe trasladarse sin revisar a otra plataforma.
En el caso ilustrativo de las solicitudes, crear el registro, entregar el aviso y asignar la tarea son momentos distintos. Si los separas, resulta más fácil saber dónde se ha producido un fallo.
Webhook y API: cómo se complementan
Con una consulta periódica, una integración pregunta si existe información nueva. Con un webhook, el sistema de origen envía un aviso cuando ocurre el evento configurado. Los dos mecanismos pueden utilizarse juntos.
Por ejemplo, el aviso puede contener solo un identificador y el receptor consultar después los detalles mediante una API. Antes de elegir, revisa qué datos incluye el evento y si son suficientes para completar el recorrido.
Si necesitas aclarar el papel de cada conexión, nuestra guía sobre qué es una API explica las comprobaciones previas y el tratamiento de errores.
Cuándo puede ser útil consultar periódicamente
Una aplicación puede no ofrecer el evento que necesitas o no conservar todos los avisos fallidos. En esos casos, una consulta de comprobación puede ayudar a detectar diferencias, si la API y sus límites lo permiten.
No conviene añadir consultas constantes sin conocer el volumen y las condiciones del proveedor. La frecuencia debería responder al tiempo de reacción que necesita el negocio.
Qué comprobar antes de activar un evento
La documentación del proveedor debería permitir responder estas preguntas:
- Qué evento dispara el aviso y cuándo se considera ocurrido.
- Qué campos se envían y cómo se identifica cada entrega.
- Cómo verifica el receptor el origen y la integridad del mensaje.
- Qué respuesta espera el emisor para considerar la entrega aceptada.
- Si existen reintentos y cómo se consultan sus resultados.
- Qué límites o cambios de versión pueden afectar a la integración.
Si alguna respuesta no está disponible, regístrala como una limitación. No asumas que todas las plataformas reintentan igual ni que entregan los eventos en el orden en que ocurrieron.
Seguridad: conocer la URL no debería bastar
Una dirección de recepción puede recibir mensajes que no procedan del emisor previsto. El receptor debe validar los mecanismos que ofrezca el proveedor, como una firma, y comprobar el contenido antes de ejecutar acciones.
No pongas secretos en lugares que se comparten habitualmente. Define quién configura el acceso, cómo se renueva y qué ocurre si deja de ser válido. Además, procesa únicamente los campos y eventos necesarios para el alcance acordado.
Separa recibir de ejecutar
Aceptar un mensaje puede significar que ha quedado registrado, no que la tarea posterior se haya completado. Si la operación tarda o depende de otra aplicación, puede tener sentido procesarla después con seguimiento propio.
El diseño debería explicar qué estado verá el equipo y cómo se detectará una tarea que no avanza. Ese seguimiento evita confundir una entrega técnica correcta con un resultado de negocio terminado.
Cómo evitar tareas duplicadas
Un mismo evento puede entregarse más de una vez según el mecanismo del proveedor o la recuperación utilizada. Si cada aviso crea directamente una tarea nueva, pueden aparecer duplicados.
Proponemos conservar el identificador del evento o una referencia adecuada del proceso y comprobar si ya se ha tratado. La regla depende del sistema: dos avisos parecidos pueden representar el mismo evento o dos cambios legítimos.
También hay que decidir qué hacer si llega una actualización antes de que exista el registro al que se refiere. La integración puede necesitar consultar el origen, dejar el caso pendiente o aplicar otra regla acordada.
Qué pruebas necesita antes de pasar a producción
Comprueba la entrega habitual, un mensaje duplicado, una firma inválida y un dato incompleto. Prueba también la indisponibilidad temporal del receptor y revisa cómo se recupera según las condiciones del emisor.
Una prueba de negocio debería seguir un caso completo hasta su resultado, no terminar cuando aparece una respuesta técnica correcta. Acordad quién valida la tarea final y dónde se consultan las excepciones.
Deja una guía para investigar fallos sin difundir datos sensibles. El equipo necesita identificar el caso, conocer su estado y saber quién puede recuperarlo de forma autorizada.
Cómo mantener la conexión después de la entrega
Asigna responsables para revisar avisos fallidos, cambios del proveedor y renovaciones de accesos. Documenta qué eventos están activos y qué proceso depende de cada uno.
Si se deja de utilizar un recorrido, revisa su suscripción y sus permisos. Mantener un receptor que nadie supervisa puede ocultar errores o generar trabajo inesperado.
En Aceleris diseñamos estas conexiones dentro de la automatización e integración de sistemas, con atención a las excepciones y al seguimiento de cada operación.
Preguntas frecuentes
¿Un webhook funciona siempre en tiempo real?
Permite avisar cuando ocurre un evento, pero la entrega y el procesamiento pueden sufrir retrasos. Comprueba las condiciones del proveedor y acuerda el tiempo de reacción necesario.
¿Hace falta programar para utilizarlo?
Algunas herramientas ofrecen conectores, pero sigue siendo necesario configurar, validar y supervisar el recorrido. La complejidad depende de las reglas y de las aplicaciones que intervienen.
¿Qué necesitamos para valorar una conexión por eventos?
Identifica qué cambio debe iniciar el trabajo, qué aplicación lo conoce y qué resultado esperas en el destino. Cuéntanos qué evento necesitas conectar y podremos revisar si existe el mecanismo adecuado y cómo comprobarlo.
