Vai al contenuto

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.

GDi

Arrivano i Webhooks v2

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:

{
  "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.

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:

Inizia subito

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

Condividi

Prova quello di cui hai appena letto.

3000 email al mese gratis. Nessuna carta di credito richiesta.

3000 email al mese gratis · Nessuna carta di credito