Webhook

I webhook permettono di ricevere notifiche HTTP POST ogni volta che avvengono eventi rilevanti nel tuo account Workledger.

Configurazione

Vai in Impostazioni → Webhook nel pannello di Workledger.
Inserisci l'URL del tuo endpoint (deve accettare richieste POST).
Seleziona gli eventi che vuoi ricevere.

HTTPS obbligatorio

L'URL del webhook deve usare HTTPS. Gli endpoint HTTP non vengono accettati.

Eventi disponibili

Evento	Descrizione
`employee.created`	Un nuovo dipendente è stato aggiunto
`employee.updated`	I dati di un dipendente sono stati modificati
`payroll.completed`	Un cedolino è stato elaborato
`payroll.approved`	Un cedolino è stato approvato
`contract.signed`	Un contratto è stato firmato

Formato del payload

Ogni notifica include un header X-Workledger-Signature per la verifica e un body JSON:

{
  "id": "evt_01H9Y4M",
  "type": "payroll.completed",
  "created_at": "2026-03-15T14:30:00Z",
  "data": {
    "payroll_id": "pay_01H9Y4N",
    "employee_id": "emp_01H8X3K",
    "period": "2026-03"
  }
}

Verifica della firma

Ogni richiesta webhook include un header X-Workledger-Signature calcolato con HMAC-SHA256:

import { createHmac } from "crypto";
 
function verifySignature(payload, signature, secret) {
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return expected === signature;
}

Importante

Verifica sempre la firma prima di elaborare il payload. Questo previene l'elaborazione di richieste non autentiche.

Retry

Se il tuo endpoint restituisce un codice di stato diverso da 2xx, Workledger ritenterà la consegna fino a 5 volte con backoff esponenziale (1 min, 5 min, 30 min, 2 ore, 24 ore).