¿Puedes confiar en este webhook? Lista de verificación para aplicaciones autoalojadas
Antes de conectar un servicio externo a una aplicación autoalojada, verifica en la documentación cómo se autentican las solicitudes, se validan los eventos y se gestionan los permisos, los secretos y los registros.
Identifica cada webhook entrante
Antes de habilitar un webhook, ¿puedes documentar quién enviará solicitudes, qué endpoint recibirá cada una y qué acciones podría desencadenar la aplicación?
Revisa cada integración por separado: ¿tiene un emisor, unos eventos, unos datos y unos efectos distintos de los demás?
- ¿Qué servicio externo debe enviar solicitudes y cómo dice la documentación que se identifica?
- ¿Cuál es la URL exacta y a qué instancia y entorno corresponde?
- ¿Qué tipos de eventos necesitas aceptar?
- ¿Qué datos se reciben y podrían incluir información personal o confidencial?
- ¿Qué cambios, mensajes o llamadas a otros servicios puede provocar cada evento?
Verifica la autenticación del emisor
Consulta la documentación oficial de la versión de la aplicación y de la integración que tienes desplegadas. ¿Qué método de autenticación documentan y cómo se configura? No des por sentado que la ruta, por sí sola, verifica quién envió la solicitud.
Comprueba por separado qué protección del transporte se configura y cómo se valida al emisor. Si no encuentras un método documentado para comprobar las solicitudes entrantes, anota esa carencia antes de habilitar el endpoint.
- ¿La documentación describe una firma u otro mecanismo de autenticación?
- ¿Qué parte de la solicitud se verifica y qué ocurre si faltan credenciales o no son válidas?
- ¿El método está disponible y habilitado en la versión y configuración que utilizas?
- Si la comprobación se configura fuera de la aplicación, ¿qué componente la aplica y quién mantiene esa configuración?
Comprueba la validación y el alcance de los eventos
¿Qué estructura, tipos, tamaños y valores acepta el endpoint, según la documentación de tu integración? Verifica que la aplicación compruebe esas condiciones antes de realizar acciones.
¿Qué sucede con los tipos de eventos desconocidos o los campos que no esperabas? Comprueba que cada evento aceptado esté vinculado a una acción prevista y limitada.
- ¿Están definidos los campos obligatorios y sus formatos para cada tipo de evento?
- ¿Hay límites documentados para el tamaño de las solicitudes y un comportamiento definido para los cuerpos incompletos o mal formados?
- ¿Se comprueba que los identificadores recibidos corresponden a la cuenta, organización o espacio de trabajo previsto?
- ¿Puedes aceptar solo los tipos de eventos que necesita la integración?
- ¿El contenido recibido puede elegir acciones o destinos con privilegios?
Revisa el tratamiento de solicitudes repetidas
¿La documentación del emisor y del receptor describe controles para solicitudes antiguas o repetidas? Comprueba qué valida el receptor; no presupongas que una solicitud aceptada anteriormente se gestiona de forma segura si vuelve a recibirse.
¿Qué hace la aplicación cuando recibe el mismo evento más de una vez? Verifica ese comportamiento para la integración concreta.
- Si se usan marcas de tiempo, ¿el receptor las valida y qué ventana de aceptación documenta?
- Si hay identificadores de eventos, ¿se usan para reconocer eventos ya procesados y durante cuánto tiempo?
- ¿Cómo se tratan los retrasos de entrega, las diferencias de reloj y las solicitudes repetidas?
- ¿Podría procesar dos veces un evento producir cambios o mensajes duplicados?
- Si la aplicación no ofrece una comprobación necesaria, ¿la documentación de la capa de integración explica cómo cubrirla?
Limita las acciones y los permisos
¿Qué identidad, token o cuenta ejecuta las acciones del webhook y qué permisos tiene? Comprueba si puedes limitar esos permisos a lo que requiere la integración.
Sigue el recorrido desde la solicitud hasta los servicios conectados. ¿Puede un evento activar operaciones que no guardan relación con su finalidad?
- ¿La aplicación permite usar una identidad o credencial específica para la integración?
- ¿Qué permisos y acceso a datos necesita realmente?
- ¿Cada tipo de evento se asocia a una acción explícita?
- ¿Qué consecuencias tendría un evento inesperado, una credencial comprometida o una configuración incorrecta?
- ¿Qué opciones documentadas de acceso o exposición están disponibles en tu despliegue?
Revisa el almacenamiento y la rotación de secretos
¿Dónde se guardan las firmas, los secretos compartidos y las credenciales de integración? Revisa quién puede acceder a ellos y si aparecen en exportaciones de configuración o información de diagnóstico.
Consulta las instrucciones del proveedor y de la aplicación para cambiar un secreto. ¿Cómo se coordinan los cambios y cómo se comprueba que el nuevo valor funciona y que el anterior ya no se acepta?
- ¿Se evitan los secretos en el código fuente y en documentación o notas de soporte de acceso amplio?
- ¿Quién puede consultar o cambiar la configuración y las credenciales?
- ¿Puedes identificar qué integración utiliza cada secreto?
- ¿Puedes probar el procedimiento de rotación en un entorno seguro?
- ¿Qué comprobación confirma que la integración funciona con el nuevo valor y que el anterior dejó de funcionar?
Comprueba qué registran la aplicación y sus componentes
¿Qué registran la aplicación y los servicios que la rodean cuando reciben o rechazan solicitudes? Revisa cuerpos, cabeceras y otros valores para determinar si podrían contener datos confidenciales o credenciales.
¿Quién puede consultar los registros, durante cuánto tiempo se conservan y qué reglas se aplican a sus copias exportadas o de respaldo?
- ¿Los registros incluyen cuerpos de solicitudes, cabeceras de autorización, firmas o cadenas de consulta?
- ¿Bastan los identificadores de eventos y los resultados de procesamiento para diagnosticar problemas sin guardar la carga útil completa?
- ¿Se revisa por separado el acceso a los registros de la aplicación, del proxy y de la integración?
- ¿Hay plazos de conservación y eliminación definidos para los registros con datos de solicitudes?
- ¿Los mensajes de error pueden revelar secretos o contenido innecesario?
Aclara qué componente aplica cada control
Para cada comprobación, identifica si la aplica la aplicación, el proveedor externo, el proxy, la integración o un procedimiento administrativo. ¿Qué componente rechaza la solicitud cuando falla una comprobación?
Si utilizas Airbip, sus capacidades verificadas incluyen ejecutar aplicaciones como cargas de trabajo de Docker en servidores en la nube de Airbip y automatizar el enrutamiento y los certificados TLS mediante Traefik y Let’s Encrypt. ¿Has comprobado también, en la documentación de la aplicación y la integración, cómo se autentican y procesan los webhooks? Las capacidades de alojamiento no confirman por sí solas ese comportamiento.
- ¿Quién configura y mantiene cada control?
- ¿Quién puede cambiar la exposición del endpoint, las credenciales y las acciones permitidas?
- ¿Has consultado la documentación oficial de la versión de la aplicación y del servicio que utilizas?
- Si no puedes verificar un control que necesitas, ¿puedes cubrir esa carencia con una capa adecuada, elegir otro método de integración o evitar habilitar el webhook?
Preguntas frecuentes
¿HTTPS basta para confiar en un webhook entrante?
Comprueba por separado qué protección del transporte se configura y cómo verifica la aplicación o la integración que la solicitud procede del emisor previsto. Consulta la documentación de las versiones que utilizas.
¿Qué hago si la aplicación no documenta la autenticación de webhooks?
Verifica la documentación oficial de la versión desplegada y de la integración. ¿Puede otra capa aplicar de forma comprobable la autenticación y las validaciones que necesitas? Si no puedes verificarlo, considera si debes habilitar el endpoint.
¿Cómo puedo probar un webhook sin usar datos de producción?
Si tu aplicación y tu integración lo permiten, usa un entorno que no sea de producción, credenciales de prueba y acciones sin efectos sobre usuarios o registros reales. Consulta qué casos de prueba admite la integración, incluidos los relacionados con autenticación, solicitudes repetidas, cargas útiles no válidas, eventos no admitidos, rotación de secretos y registros.
¿Es seguro incluir secretos y cargas útiles en los registros?
Revisa qué registran la aplicación y los servicios que la rodean, quién puede acceder a esos registros y cuánto tiempo se conservan. Comprueba si puedes diagnosticar los problemas sin guardar cabeceras con secretos o cargas útiles confidenciales completas.
Fuentes y lecturas adicionales
- Docker documentation — Docker
- Traefik documentation — Traefik Labs
- Let’s Encrypt documentation — Internet Security Research Group
- NIST Cybersecurity Framework — NIST
- OWASP Application Security Verification Standard — OWASP