Riferimento Webhook

I Webhook inviano richieste HTTP POST al tuo endpoint quando si verificano eventi in Umbrella, così non devi interrogare periodicamente l’API per rilevare le modifiche.

Configurazione

1. Vai su Dashboard > Impostazioni > Integrazioni > Webhook
2. Fai clic su Aggiungi endpoint Webhook
3. Inserisci l’URL HTTPS del tuo endpoint
4. Seleziona gli eventi che vuoi ricevere
5. Salva e conserva il segreto di firma (viene mostrato una sola volta)

Il tuo endpoint deve accettare richieste POST, restituire uno stato 2xx entro 30 secondi e accettare application/json.

Tipi di evento

Eventi delle polizze

Eventi dei sinistri

Eventi di registrazione

Eventi delle garanzie

Struttura del payload

Ogni Webhook segue questo involucro:

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "claim.submitted",
  "timestamp": "2025-03-15T14:30:00.000Z",
  "apiVersion": "1.3.9",
  "orgId": "org_xyz789",
  "data": { ... }
}

• id — ID univoco dell’evento (usalo per la deduplicazione)
• type — tipo di evento
• timestamp — quando si è verificato l’evento
• data — payload specifico dell’evento con i dettagli della risorsa interessata (polizza, sinistro, registrazione e così via)

Verifica della firma

Ogni richiesta include un’intestazione X-Umbrella-Signature con un hash HMAC-SHA256 del corpo della richiesta. Verificala prima di elaborare gli eventi.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Criteri di ripetizione

Le consegne non riuscite (risposta non 2xx, timeout, errore di connessione) vengono ritentate con backoff esponenziale:

Dopo 7 tentativi falliti, la consegna viene contrassegnata come non riuscita. Una risposta 410 Gone disattiva l’endpoint in modo permanente.

Test

1. Vai su Dashboard > Impostazioni > Integrazioni > Webhook
2. Fai clic sul tuo endpoint, poi su Invia test
3. Seleziona un tipo di evento ed esamina il risultato della consegna

La pagina di dettaglio del Webhook mostra anche un registro delle consegne recenti, con codici di stato e tempi.

Correlati

• Autenticazione — Sicurezza e credenziali dell’API
• API Sinistri — Endpoint per la gestione dei sinistri
• API Polizze — Endpoint per la gestione delle polizze