Recibe avisos con webhooks

Los webhooks avisan a tus sistemas en el mismo momento en que algo ocurre en Bueggio HR — sin polling. Cada entrega va firmada según la especificación Standard Webhooks, se reintenta automáticamente si falla y queda anotada en un registro de entregas que puedes consultar.

Los eventos

Evento	Se dispara cuando
leave_request.created	Alguien pide una ausencia (pendiente o autoaprobada)
leave_request.approved	Se aprueba una solicitud
leave_request.declined	Se rechaza una solicitud
leave_request.cancelled	Se cancela una reserva
user.created	Una persona se une a la organización
user.deactivated	Una persona es desactivada

Añade un endpoint

1. Ve a Ajustes → Integraciones → Webhooks.
2. Introduce la URL HTTPS de tu endpoint y marca los eventos que quieres recibir.
3. Haz clic en Añadir endpoint. Bueggio HR genera un secret de firma (whsec_…) — cópialo en tu receptor para verificar las firmas.
4. Haz clic en Enviar ping de prueba y mira el registro de entregas: un 2xx en verde significa que todo está conectado.

Verifica la firma

Cada entrega es un POST JSON con tres cabeceras:

• webhook-id — id único del mensaje (también tu clave de deduplicación).
• webhook-timestamp — segundos Unix; rechaza los timestamps antiguos para prevenir replays.
• webhook-signature — v1,<base64>: un HMAC-SHA256 de id.timestamp.body con tu secret.

Como es el esquema Standard Webhooks, no tienes que implementarlo a mano — las bibliotecas oficiales (JavaScript, Python, Ruby, Go, PHP…) lo verifican en una llamada. Responde con cualquier estado 2xx cuando hayas aceptado el mensaje.

Reintentos y registro de entregas

Si tu endpoint está caído o responde con error, la entrega se reintenta hasta 5 veces con esperas crecientes y después se marca como fallida. El registro de entregas junto a cada endpoint muestra cada intento con su código de respuesta — el primer sitio donde mirar cuando algo no llega.

Registrar endpoints desde código

Los endpoints también se pueden crear y quitar vía API (POST /api/v1/webhooks) — útil para herramientas que auto-registran sus URL de disparo, como n8n.

Solución de problemas

• No llega nada — mira primero el registro de entregas: si no hay filas, el evento no está suscrito; si las filas están en rojo, tu endpoint rechaza o no es alcanzable.
• La verificación de firma falla — asegúrate de verificar sobre el cuerpo en bruto de la petición (antes de cualquier parseo JSON) y de usar el secret tal como lo espera tu biblioteca, incluida la gestión del prefijo whsec_.
• Eventos duplicados — los reintentos pueden entregar un mensaje más de una vez; deduplica por webhook-id.