Resumen
Los webhooks permiten que la Safety App notifique a otro sistema en el momento en que algo sucede en tu cuenta: se envía un incidente, cambia una investigación, se completa una acción correctiva. Registras una dirección capaz de recibir esas notificaciones, eliges qué eventos deben llegar a ella, y opcionalmente agregas un secreto de firma para que el sistema receptor pueda confirmar que cada mensaje realmente vino de la Safety App. Este artículo cubre cómo crear un webhook, asegurarlo, monitorear sus entregas, y eliminarlo.
Introducción
La mayoría de los programas de seguridad conviven con otras herramientas: un espacio de chat donde el equipo ya conversa, un servicio de automatización que abre tickets, un almacén de datos para reportes, un panel operativo. Sin webhooks, esos sistemas tienen que preguntarle repetidamente a la Safety App si algo ha cambiado. Con webhooks, la Safety App se lo dice a medida que ocurre cada evento.
Los webhooks los configuran los Super Admin en la configuración de la cuenta. Resuelven el problema del retraso y la duplicación entre sistemas: en lugar de que alguien vuelva a ingresar un incidente en una segunda herramienta, o de que un panel que se actualiza por temporizador quede rezagado frente a la realidad, el sistema receptor recibe el aviso en cuanto ocurre el evento y puede actuar de inmediato.
Conceptos clave
- Webhook: una conexión guardada entre tu cuenta de la Safety App y una dirección externa, que cubre un conjunto elegido de eventos. Cada webhook tiene su propio nombre, dirección, selección de eventos, e historial de entregas.
- Endpoint: la dirección en un servidor que tú controlas y que recibe las notificaciones. Debe ser accesible mediante una conexión segura y capaz de aceptar solicitudes entrantes.
- Evento: aquello específico que sucede en la Safety App —como el envío de un incidente o la finalización de una acción correctiva— que hace que un webhook se dispare.
- Secreto de firma: un valor opcional que defines en un webhook. La Safety App lo usa para firmar cada mensaje que envía, de modo que el sistema receptor pueda confirmar que el mensaje es genuino y no fue alterado en el camino.
- Registro de entregas: el historial de los intentos de envío recientes de un webhook, que muestra el evento, si el intento tuvo éxito, la respuesta que devolvió tu endpoint, cualquier mensaje de error, y la hora del intento.
- Failures: el número de entregas recientes que no tuvieron éxito, mostrado en la lista de webhooks para que una conexión rota destaque sin necesidad de abrir el registro.
Pasos a seguir
Abre la configuración de Webhooks
Inicia sesión como Super Admin, abre Settings, luego el grupo Integrations, y luego Webhooks. La página lista cada webhook configurado en tu cuenta. Junto a cada uno puedes ver si está Active, cuántos Failures recientes ha registrado, y cuándo fue su Last Triggered, lo que en conjunto te da una lectura rápida de la salud de cada conexión.
Prepara un endpoint para recibir notificaciones
Antes de crear el webhook, asegúrate de tener una dirección que acepte solicitudes entrantes mediante una conexión segura, y de que la controlas. El sistema receptor debe acusar recibo de cada mensaje con prontitud: si tu endpoint responde con un error o tarda demasiado en responder, el intento se registra como una entrega fallida y no como exitosa. Conviene confirmar que el endpoint funciona antes de apuntar la Safety App hacia él, para que cualquier falla inicial sea fácil de interpretar.
Crea un webhook
Selecciona + New Webhook y completa el formulario:
- Name identifica la conexión en la lista. Usa algo que indique a dónde van los mensajes y por qué, para que un colega que revise la lista más adelante entienda su propósito.
- URL es la dirección segura completa de tu endpoint.
- Events determina qué cambios disparan un mensaje. Puedes enviar varios eventos a un mismo endpoint, o crear un webhook separado por evento si prefieres mantener cada flujo independiente.
- Secret (for HMAC signing) es opcional pero muy recomendable, y se explica más abajo.
Selecciona Create. El webhook queda activo de inmediato y enviará en el próximo evento coincidente.
Leyenda: Selecciona + New Webhook y completa el formulario.
Elige qué eventos enviar
La Safety App puede notificar a tu endpoint cuando se envía un nuevo reporte de incidente, cuando se edita un incidente, y cuando un incidente pasa a un nuevo estado. Del lado de las investigaciones, puede avisarte cuando se abre una nueva investigación y cuando se edita una existente. Para las acciones correctivas y preventivas, puede enviar un mensaje cuando se crea una acción, cuando se actualiza, y cuando se marca como completada. También puede notificarte cuando se registra una decisión de revisión de cumplimiento, y cuando se crea una asignación de capacitación para un usuario.
Selecciona solo los eventos sobre los que el sistema receptor realmente va a actuar. Un webhook suscrito a todo genera tráfico que el otro lado tiene que filtrar, y hace más difícil leer el registro de entregas cuando estás diagnosticando un problema.
Leyenda: La Safety App puede notificar a tu endpoint cuando se envía un nuevo reporte de incidente, cuando se edita un incidente, y cuando un incidente pasa a un nuevo estado.
Asegura las entregas con un secreto de firma
Si ingresas un valor en el campo Secret (for HMAC signing), la Safety App firmará cada solicitud que envíe a ese endpoint, enviando la firma junto con el mensaje. Tu sistema receptor puede entonces recalcular la firma a partir del mismo secreto y comparar ambas antes de actuar.
Esto importa porque un endpoint que acepta mensajes sin firmar actuará sobre cualquier cosa que se envíe a su dirección, venga de quien venga, si alguien la descubre. Verificar la firma es la diferencia entre un endpoint que confía en la Safety App y uno que confía en quienquiera que le escriba. Comparte el secreto únicamente con el sistema que lo necesita, y trátalo con el mismo cuidado que una contraseña.
Revisa los registros de entrega y gestiona los webhooks
Para comprobar si un webhook está funcionando, selecciona el icono de historial en su fila. Se abre el registro de entregas y muestra los intentos recientes con el evento, el resultado, la respuesta que devolvió tu endpoint, cualquier mensaje de error, y la marca de tiempo. Este es el primer lugar donde mirar cuando un sistema posterior deja de reaccionar, porque te dice si la Safety App envió el mensaje y qué respondió tu endpoint.
Cada fila ofrece además un icono de edición, para cambiar el nombre, la dirección, los eventos, o el secreto, y un icono de eliminación, que borra el webhook de forma permanente y detiene todas las entregas posteriores a ese endpoint.
Conclusión
Un webhook convierte un cambio en la Safety App en un mensaje inmediato para un sistema que necesita enterarse. Dale a cada conexión un nombre claro, suscríbela solo a los eventos sobre los que su receptor actúa, define siempre un secreto de firma para que el lado receptor pueda verificar lo que recibe, y usa el registro de entregas como tu primer diagnóstico cuando algo posterior se quede en silencio. Configurados así, los webhooks mantienen actualizados los sistemas que rodean tu programa de seguridad sin que nadie copie datos entre ellos.