Annunciamo i Webhook v2

Stiamo lanciando Webhooks v2, una completa rivisitazione del modo in cui Emailit invia notifiche di eventi in tempo reale alle tue applicazioni. Con 36 tipi di eventi distribuiti su 9 categorie di risorse, verifica crittografica delle firme e una solida politica di retry, Webhooks v2 ti offre tutto ciò che serve per costruire integrazioni affidabili basate sugli eventi.

Cosa c’è di nuovo

36 tipi di eventi su 9 risorse

Webhooks v2 copre ogni risorsa 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 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 arrivo accettata
email.complained	Segnalazione spam registrata
email.clicked	Un link nell’email è stato cliccato
email.loaded	Il contenuto dell’email è stato caricato (aperta)

Eventi CRUD per domini, audience, 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 segue la stessa forma, rendendo semplice costruire un singolo 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 tuo webhook secret utilizzando 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

Raccomandiamo vivamente di utilizzare un confronto timing-safe (ad es. crypto.timingSafeEqual in Node.js) per prevenire attacchi di timing, e di rifiutare richieste con timestamp più vecchi di qualche minuto per proteggersi da attacchi replay.

Esempi completi di verifica in Node.js, Python, PHP, Ruby e Go sono disponibili nella documentazione Firma della Richiesta.

Retry 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

Sono 7 tentativi totali nell’arco di circa 41 ore. Dopo l’ultimo tentativo, il webhook viene automaticamente disabilitato. Puoi riattivarlo dalla dashboard 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 rapidamente — Restituisci un 2xx immediatamente e processa il payload in modo asincrono in un job in background.
• Gestisci i duplicati — Lo stesso evento potrebbe essere consegnato più di una volta durante i retry. Usa event_id per deduplicare.
• Verifica le firme — Valida sempre l’header X-Emailit-Signature per confermare che la richiesta provenga da Emailit.
• Proteggiti dagli attacchi replay — Controlla l’X-Emailit-Timestamp e rifiuta richieste più vecchie di qualche minuto.

Documentazione completa

Abbiamo pubblicato la documentazione completa per 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 — Lista completa di tutti i 36 tipi di eventi
• Richieste Webhook — Formato delle richieste, header e politica di retry
• Firma della Richiesta — Verifica della firma con esempi di codice in 5 linguaggi

Inizia subito

Vai alla documentazione Webhooks per iniziare, oppure passa direttamente al Riferimento API per creare il tuo primo endpoint webhook.