Webhook

Configurazione dei Webhook

Umbrella invia notifiche Webhook ai tuoi sistemi esterni quando si verificano eventi legati alle garanzie. Usa i Webhook per integrarti con il tuo CRM, il tuo helpdesk, i tuoi strumenti di analisi o i tuoi servizi backend.

---

Tipi di evento

Eventi delle polizze

Evento	Descrizione
policy.created	Polizza di garanzia creata (ordine completato con garanzia)
policy.activated	Polizza attivata (pagamento confermato)
policy.expired	La polizza ha raggiunto la data di scadenza
policy.cancelled	Polizza annullata (rimborso o annullamento dell’ordine)
policy.updated	Polizza aggiornata (modifica dello stato o dei metadati)

Eventi dei sinistri

Evento	Descrizione
claim.created	Nuovo sinistro aperto
claim.updated	Stato del sinistro modificato
claim.approved	Sinistro approvato
claim.denied	Sinistro respinto
claim.resolved	Sinistro risolto (sostituzione spedita o rimborso emesso)

Eventi degli ordini

Evento	Descrizione
order.warranty_attached	Garanzia associata a una riga d’ordine
order.warranty_removed	Garanzia rimossa da un ordine
order.post_purchase_completed	Upsell post-acquisto della garanzia completato

Eventi dei clienti

Evento	Descrizione
customer.policy_assigned	Polizza assegnata a un cliente
customer.claim_filed	Il cliente ha aperto un sinistro

---

Formato del payload

Tutti i payload seguono questa struttura:

{
  "id": "wh_evt_abc123def456",
  "event": "policy.created",
  "timestamp": "2026-03-17T14:30:00.000Z",
  "version": "1.0",
  "data": { ... },
  "metadata": {
    "orgId": "org_abc",
    "integrationPlatform": "shopify",
    "shopDomain": "my-store.myshopify.com"
  }
}

• id — ID univoco dell’evento (usalo per la deduplicazione)
• event — tipo di evento
• data — payload specifico dell’evento con i dettagli della risorsa
• metadata — contesto dell’organizzazione e dell’integrazione

---

Verifica della firma

Tutti i Webhook includono un header X-Umbrella-Signature (HMAC-SHA256 del corpo della richiesta). Verificalo sempre prima di elaborare la richiesta. Consulta il Riferimento Webhook per esempi di codice di verifica.

---

Criteri di ritentativo

Le consegne non riuscite (risposta diversa da 2xx o timeout) vengono ritentate con backoff esponenziale:

Tentativo	Ritardo
1° ritentativo	30 secondi
2° ritentativo	2 minuti
3° ritentativo	10 minuti
4° ritentativo	1 ora
5° ritentativo	6 ore
Ritentativo finale	24 ore

Il tuo endpoint deve rispondere con 200, 201 o 202 entro 30 secondi. Rispondi subito ed elabora in modo asincrono per evitare i timeout.

---

Configurare un endpoint

1. Vai su Dashboard → Impostazioni → Webhook
2. Fai clic su Aggiungi endpoint
3. Inserisci l’URL HTTPS del tuo endpoint e seleziona gli eventi
4. Copia e conserva in modo sicuro il segreto di firma (viene mostrato una sola volta)
5. Esegui un test con Invia test nella pagina di dettaglio dell’endpoint

---

Log dei Webhook

La pagina dei log mostra lo storico delle consegne per ogni endpoint: tipo di evento, stato (riuscito/non riuscito/ritentato), codice di risposta, tempo di risposta, data e ora e numero di tentativi.

---

Correlati

• Sincronizzazione dei prodotti Shopify — Sincronizzazione dei Webhook di Shopify
• Integrazione Shopify — Connessione generale con Shopify
• Configurazione del widget — Impostazioni di visualizzazione del widget