Panoramica
Webhook
Ricevi notifiche HTTP firmate quando le email vengono consegnate, rimbalzano, vengono aperte o cliccate, arrivano sul tuo dominio di ricezione, o quando cambiano le risorse.
I webhook inviano gli eventi da Emailit alla tua applicazione nel momento in cui si verificano, così non devi interrogare periodicamente l’API. Usali per aggiornare lo stato di consegna nel tuo database, smettere di scrivere agli indirizzi che rimbalzano o segnalano spam, reagire ad aperture e clic, elaborare le email in entrata o sincronizzare contatti e soppressioni.
Come funziona
- Registri un endpoint. Crea un webhook con un nome e un URL HTTPS nel pannello o con l’API. Emailit genera un secret di firma per il webhook.
- Succede qualcosa. Emailit registra un evento, ad esempio
email.delivered, e lo mette in coda per ogni webhook attivo che sottoscrive quel tipo di evento e il cui filtro sul payload corrisponde. - Emailit invia un batch. Entro pochi secondi, Emailit invia una richiesta
POSTil cui corpo è un array JSON con fino a 100 eventi in coda, a partire dal meno recente. Le richieste verso uno stesso webhook vengono inviate una alla volta. - Il tuo endpoint risponde. Qualsiasi stato
2xxentro 30 secondi segna come consegnati tutti gli eventi del batch. Qualsiasi altro esito, compresi un timeout o un reindirizzamento, è un errore, e il batch viene ritentato per circa tre giorni.
Ogni richiesta ha questi header:
| Header | Valore |
|---|---|
Content-Type |
application/json |
User-Agent |
Emailit-Webhooks/2.0 |
X-Emailit-Signature |
HMAC-SHA256 in esadecimale di {timestamp}.{raw body}, calcolato con il secret del webhook come chiave. |
X-Emailit-Timestamp |
Ora Unix in secondi del momento in cui la richiesta è stata firmata. |
Vedi Richieste webhook per il formato completo e Firma delle richieste per il codice di verifica.
Esempio rapido
Questo handler Express verifica la firma, poi gestisce ogni evento del batch:
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/webhooks/emailit', express.raw({ type: 'application/json' }), (req, res) => {
const timestamp = req.get('X-Emailit-Timestamp') ?? '';
const signature = req.get('X-Emailit-Signature') ?? '';
const expected = crypto
.createHmac('sha256', process.env.EMAILIT_WEBHOOK_SECRET) // whsec_...
.update(`${timestamp}.`)
.update(req.body)
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
const a = Buffer.from(signature);
const b = Buffer.from(expected);
const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
if (!fresh || !valid) return res.status(401).send('Invalid signature');
for (const event of JSON.parse(req.body)) {
switch (event.type) {
case 'email.delivered':
console.log(`Delivered ${event.data.object.id} to ${event.data.object.to}`);
break;
case 'email.bounced':
case 'email.complained':
console.log(`Stop sending to ${event.data.object.to}`);
break;
}
}
res.sendStatus(200);
});
app.listen(3000);Cosa puoi sottoscrivere
I webhook coprono la consegna e l’engagement delle email (email.delivered, email.bounced, email.clicked e altri), la posta in entrata (email.received) e le modifiche a domini, liste, iscritti, contatti, segmenti tracciati, template, soppressioni, verifiche email e campagne. Un nuovo webhook creato nel pannello riceve tutti gli eventi; in seguito puoi limitarlo a tipi specifici. Vedi Tipi di evento.
Nei piani Pro, Business e Custom, un filtro sul payload può limitare un webhook agli eventi che corrispondono a determinate regole, ad esempio solo le email dirette a un dominio.
Limiti
| Pay as you go | Pro | Business | Custom | |
|---|---|---|---|---|
| Endpoint webhook | 3 | 10 | 100 | Flessibile |
| Filtri sul payload dei webhook | — | Fino a 25 regole | Fino a 25 regole | Fino a 25 regole |
La pagina dei webhook mostra quanti endpoint stai usando, ad esempio 2/3 used. Quando raggiungi il limite, il pulsante Add webhook viene disattivato finché non ne elimini uno o non passi a un piano superiore. Ogni webhook può inviare al massimo 5 eventi di test al minuto.