Richieste Webhook

Quando si verifica un evento, Emailit invia una richiesta HTTP POST all’URL webhook che hai configurato. Questa pagina descrive il formato della richiesta, gli header e il comportamento di consegna.

Formato della richiesta

Tutte le richieste webhook vengono inviate come richieste POST con un corpo JSON:

Metodo: POST
Content-Type: application/json
Timeout: 30 secondi

Ogni richiesta webhook include i seguenti header:

Header	Descrizione
`Content-Type`	`application/json`
`User-Agent`	`Emailit-Webhooks/2.0`
`X-Emailit-Signature`	Firma HMAC-SHA256 per verificare l’autenticità
`X-Emailit-Timestamp`	Timestamp Unix di quando la richiesta è stata firmata

Corpo della richiesta

Il corpo della richiesta contiene il payload dell’evento in formato JSON:

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

Risposta attesa

Il tuo endpoint dovrebbe restituire un codice di stato 2xx (ad esempio 200, 201, 204) per confermare la ricezione. Qualsiasi altro codice di stato viene considerato un errore.

Politica di ripetizione

Se il tuo endpoint non risponde con un codice di stato 2xx entro 30 secondi, Emailit riproverà la consegna secondo il seguente programma:

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

Dopo il tentativo 6 (7 tentativi totali), il webhook viene automaticamente disabilitato. Puoi riattivarlo dalla dashboard di Emailit.

Ordinamento

Gli eventi webhook vengono consegnati quasi in tempo reale ma non è garantito che arrivino in ordine. Utilizza l’event_id e i timestamp all’interno del payload dell’evento per gestire l’ordinamento nella tua applicazione.

Indirizzi IP

Le richieste webhook vengono inviate dall’infrastruttura di Emailit. Se devi inserire degli IP in whitelist, contatta il supporto per l’elenco aggiornato degli indirizzi IP in uscita.

Migliori pratiche

Rispondi rapidamente — Elabora il webhook in modo asincrono e restituisci immediatamente un 2xx. Esegui le elaborazioni pesanti in un job in background.
Gestisci i duplicati — Usa l’event_id per deduplicare gli eventi. Lo stesso evento potrebbe essere consegnato più di una volta durante i tentativi.
Verifica le firme — Valida sempre l’header X-Emailit-Signature per assicurarti che la richiesta provenga da Emailit. Vedi Firma della Richiesta.