Ricevi notifiche con i webhook

I webhook avvisano i tuoi sistemi nel momento esatto in cui succede qualcosa in Bueggio HR — senza polling. Ogni consegna è firmata secondo la specifica Standard Webhooks, ritentata automaticamente in caso di errore e registrata in un log delle consegne che puoi consultare.

Gli eventi

Evento	Scatta quando
leave_request.created	Qualcuno richiede un'assenza (in attesa o auto-approvata)
leave_request.approved	Una richiesta viene approvata
leave_request.declined	Una richiesta viene rifiutata
leave_request.cancelled	Una richiesta viene annullata
user.created	Una persona entra nell'organizzazione
user.deactivated	Una persona viene disattivata

Aggiungi un endpoint

1. Vai in Impostazioni → Integrazioni → Webhook.
2. Inserisci l'URL HTTPS del tuo endpoint e spunta gli eventi che vuoi ricevere.
3. Clicca Aggiungi endpoint. Bueggio HR genera un secret di firma (whsec_…) — copialo nel tuo ricevitore per verificare le firme.
4. Clicca Invia ping di prova e controlla il log consegne: un 2xx verde significa che il collegamento funziona.

Verifica la firma

Ogni consegna è una POST JSON con tre header:

• webhook-id — id univoco del messaggio (anche la tua chiave di deduplica).
• webhook-timestamp — secondi Unix; rifiuta i timestamp vecchi per prevenire i replay.
• webhook-signature — v1,<base64>: un HMAC-SHA256 di id.timestamp.body con il tuo secret.

Essendo lo schema Standard Webhooks, non devi implementarlo a mano — le librerie ufficiali (JavaScript, Python, Ruby, Go, PHP…) lo verificano in una chiamata. Rispondi con un qualsiasi stato 2xx quando hai accettato il messaggio.

Ritentativi e log consegne

Se il tuo endpoint è giù o risponde con un errore, la consegna viene ritentata fino a 5 volte con attese crescenti, poi segnata come fallita. Il log consegne accanto a ogni endpoint mostra ogni tentativo con il suo codice di risposta — il primo posto dove guardare quando qualcosa non arriva.

Registrare endpoint da codice

Gli endpoint si possono anche creare e rimuovere via API (POST /api/v1/webhooks) — utile per gli strumenti che auto-registrano i propri URL trigger, come n8n.

Problemi comuni

• Non arriva nulla — guarda prima il log consegne: se non ci sono righe, l'evento non è sottoscritto; se le righe sono rosse, il tuo endpoint rifiuta o è irraggiungibile.
• La verifica della firma fallisce — assicurati di verificare sul body grezzo della richiesta (prima di qualsiasi parsing JSON) e di usare il secret come se lo aspetta la tua libreria, gestione del prefisso whsec_ compresa.
• Eventi duplicati — i ritentativi possono consegnare un messaggio più di una volta; deduplica su webhook-id.