# Arrivano i Webhooks v2

> Sono arrivati i Webhooks v2: 36 tipi di eventi, firme HMAC-SHA256, nuovi tentativi automatici e documentazione completa per ogni payload.

2026-02-26 · George (https://x.com/thegeorge, https://www.linkedin.com/in/jiri-zizka/)

Lanciamo i **Webhooks v2**, una revisione completa del modo in cui Emailit invia notifiche di eventi in tempo reale alle tue applicazioni. Con 36 tipi di eventi in 9 categorie di risorse, la verifica crittografica delle firme e una solida politica di nuovi tentativi, i Webhooks v2 ti danno tutto ciò che serve per costruire integrazioni affidabili basate sugli eventi.

## Cosa c’è di nuovo

### 36 tipi di eventi su 9 risorse

I Webhooks v2 coprono tutte le risorse di Emailit. Puoi iscriverti esattamente agli eventi che ti interessano oppure utilizzare `all_events` per ricevere tutto.

**Gli eventi email** tracciano l’intero ciclo di vita della consegna:

| Evento | Descrizione |
| --- | --- |
| `email.accepted` | Accettata per la consegna |
| `email.scheduled` | Programmata per una consegna futura |
| `email.delivered` | Consegnata al server di posta del destinatario |
| `email.bounced` | Fallita definitivamente (hard bounce) |
| `email.attempted` | Fallimento temporaneo della consegna |
| `email.failed` | Fallita a causa di un errore specifico |
| `email.rejected` | Accettata poi rifiutata |
| `email.suppressed` | Il destinatario è nella lista di soppressione |
| `email.received` | Email in entrata accettata |
| `email.complained` | Segnalazione di spam registrata |
| `email.clicked` | Un link nell’email è stato cliccato |
| `email.loaded` | Il contenuto dell’email è stato caricato (aperta) |

**Eventi CRUD** per domini, liste, iscritti, contatti, template, soppressioni, verifiche email e liste di verifica email, ciascuno con eventi `.created`, `.updated` e `.deleted`.

### Struttura degli eventi coerente

Ogni payload webhook ha la stessa struttura, quindi è semplice costruire un unico gestore per tutti gli eventi:

```json
{
  "event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
      "object": "email",
      ...
    }
  }
}
```

L’`event_id` identifica univocamente ogni evento, `type` ti dice cosa è successo, e `data.object` contiene la risorsa completa al momento dell’evento.

### Verifica della firma HMAC-SHA256

Ogni richiesta webhook è firmata con il secret del tuo webhook tramite HMAC-SHA256. La firma è calcolata su `{timestamp}.{rawBody}`, così puoi verificare sia l’autenticità che la freschezza in un solo passaggio.

Ogni richiesta include due header:

- `X-Emailit-Signature` — il digest esadecimale HMAC-SHA256
- `X-Emailit-Timestamp` — il timestamp Unix utilizzato nella firma

Ti consigliamo vivamente di usare un confronto timing-safe (ad esempio `crypto.timingSafeEqual` in Node.js) per prevenire i timing attack e di rifiutare le richieste con timestamp più vecchi di qualche minuto per proteggerti dai replay attack.

Trovi esempi completi di verifica in Node.js, Python, PHP, Ruby e Go nella documentazione sulla [firma delle richieste](https://emailit.com/docs/webhooks/request-signature).

### Nuovi tentativi automatici con backoff esponenziale

Se il tuo endpoint non risponde con un `2xx` entro 30 secondi, Emailit riprova automaticamente:

| Tentativo | Ritardo |
| --- | --- |
| 0 | 5 secondi |
| 1 | 5 minuti |
| 2 | 30 minuti |
| 3 | 2 ore |
| 4 | 5 ore |
| 5 | 10 ore |
| 6 | 24 ore |

In totale sono 7 tentativi nell’arco di circa 41 ore. Dopo l’ultimo tentativo il webhook viene disattivato automaticamente. Puoi riattivarlo dal pannello in qualsiasi momento.

## Formato delle richieste

Tutte le richieste webhook sono `POST` con un body JSON. Ogni richiesta include questi header:

| Header | Descrizione |
| --- | --- |
| `Content-Type` | `application/json` |
| `User-Agent` | `Emailit-Webhook/1.0` |
| `X-Emailit-Signature` | Firma HMAC-SHA256 |
| `X-Emailit-Timestamp` | Timestamp Unix utilizzato nella firma |

## Best practice

- **Rispondi subito** — Restituisci immediatamente un `2xx` ed elabora il payload in modo asincrono, in un job in background.
- **Gestisci i duplicati** — Durante i nuovi tentativi lo stesso evento potrebbe arrivare più di una volta. Usa `event_id` per eliminare i duplicati.
- **Verifica le firme** — Valida sempre l’header `X-Emailit-Signature` per confermare che la richiesta provenga da Emailit.
- **Proteggiti dai replay attack** — Controlla l’header `X-Emailit-Timestamp` e rifiuta le richieste più vecchie di qualche minuto.

## Documentazione completa

Abbiamo pubblicato la documentazione completa dei Webhooks v2, con esempi dettagliati di payload e descrizioni dei campi per tutti i 36 eventi:

- [Introduzione](https://emailit.com/docs/webhooks) — Panoramica e come funzionano i webhook
- [Tipi di eventi](https://emailit.com/docs/webhooks/event-types) — Elenco completo dei 36 tipi di eventi
- [Richieste webhook](https://emailit.com/docs/webhooks/webhook-requests) — Formato delle richieste, header e politica dei nuovi tentativi
- [Firma delle richieste](https://emailit.com/docs/webhooks/request-signature) — Verifica della firma con esempi di codice in 5 linguaggi

## Inizia subito

Vai alla [documentazione dei webhook](https://emailit.com/docs/webhooks) per iniziare, oppure passa direttamente al [riferimento API](https://emailit.com/docs/api-reference/webhooks/create) per creare il tuo primo endpoint webhook.

---

Source: https://emailit.com/it/blog/annuncio-webhooks-v2/
