Annunci5 min di lettura
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.
GDiGeorge

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 |
|---|---|
| Accettata per la consegna |
| Programmata per una consegna futura |
| Consegnata al server di posta del destinatario |
| Fallita definitivamente (hard bounce) |
| Fallimento temporaneo della consegna |
| Fallita a causa di un errore specifico |
| Accettata poi rifiutata |
| Il destinatario è nella lista di soppressione |
| Email in entrata accettata |
| Segnalazione di spam registrata |
| Un link nell’email è stato cliccato |
| 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:
{
"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-SHA256X-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.
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 |
|---|---|
|
|
|
|
| Firma HMAC-SHA256 |
| Timestamp Unix utilizzato nella firma |
Best practice
- Rispondi subito — Restituisci immediatamente un
2xxed 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_idper eliminare i duplicati. - Verifica le firme — Valida sempre l’header
X-Emailit-Signatureper confermare che la richiesta provenga da Emailit. - Proteggiti dai replay attack — Controlla l’header
X-Emailit-Timestampe 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 — Panoramica e come funzionano i webhook
- Tipi di eventi — Elenco completo dei 36 tipi di eventi
- Richieste webhook — Formato delle richieste, header e politica dei nuovi tentativi
- Firma delle richieste — Verifica della firma con esempi di codice in 5 linguaggi
Inizia subito
Vai alla documentazione dei webhook per iniziare, oppure passa direttamente al riferimento API per creare il tuo primo endpoint webhook.


