Configura un webhook

Questa guida crea un webhook, lo limita agli eventi che ti servono e controlla che il tuo endpoint riceva richieste firmate. Puoi fare tutto nel pannello o con l’API dei webhook.

Prima di iniziare

• Un URL pubblico che accetti richieste POST. HTTPS è fortemente consigliato. Gli URL su localhost o su intervalli di IP privati vengono rifiutati; per lo sviluppo in locale, usa un tunnel come ngrok o Cloudflare Tunnel.
• Un endpoint che conservi il corpo grezzo della richiesta, così da poter verificare la firma.
• Per l’API, una chiave con Full Access.
• Uno slot libero per un webhook. Pay as you go include 3 endpoint, Pro 10, Business e Custom 100.

Crea il webhook

curl https://api.emailit.com/v2/webhooks \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production events",
    "url": "https://acme.com/webhooks/emailit",
    "events": ["email.delivered", "email.bounced", "email.complained"]
  }'

Scegli gli eventi

Un webhook riceve tutti i tipi di evento oppure solo quelli che selezioni.

curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"all_events": false, "events": ["email.received", "email.held", "email.canceled"]}'

Filtra gli eventi per payload

Un filtro sul payload consegna un evento solo quando i suoi dati corrispondono alle tue regole. I filtri si applicano in aggiunta alla selezione degli eventi: un evento deve essere sottoscritto e corrispondere al filtro.

Usalo per dividere il traffico tra più endpoint, ad esempio un webhook per ogni linea di prodotto, o per scartare eventi che altrimenti ignoreresti nel codice.

• Modalità di corrispondenza: All rules match (all) oppure Any rule matches (any).
• Regole: fino a 25. Ogni regola ha un campo, un operatore e un valore.
• Campo: un percorso con punti all’interno del data.object dell’evento, ad esempio to, status, meta.plan o, per gli eventi di clic, link.url. Il prefisso payload. è facoltativo, quindi payload.from e from sono equivalenti.
• I confronti distinguono tra maiuscole e minuscole e confrontano i valori come testo, tranne greater_than e less_than, che confrontano numeri.

curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": "all",
      "rules": [
        { "field": "to", "operator": "ends_with", "value": "@acme.com" },
        { "field": "meta.plan", "operator": "in", "value": ["pro", "business"] }
      ]
    }
  }'

Altri esempi:

Se un workspace passa a Pay as you go, i filtri esistenti restano salvati ma vengono ignorati, e tutti gli eventi sottoscritti vengono consegnati.

Invia un evento di test

Un test invia subito un evento di esempio al tuo URL, firmato con il secret attuale del webhook. Gli eventi sottoscritti e i filtri vengono ignorati, la richiesta non viene ritentata e non compare nella scheda Requests. Ogni webhook consente 5 test al minuto.

curl https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e/test \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "email.delivered"}'

Gli eventi di test usano dati di esempio, con un event_id che inizia con evt_test_, e la loro struttura può differire leggermente da quella degli eventi reali. Scrivi l’handler basandoti sul riferimento eventi e confermalo con un invio reale.

Attiva o disattiva un webhook

Disattiva un webhook per interrompere le consegne senza perderne le impostazioni, ad esempio durante una manutenzione.

• Pannello: apri il menu delle azioni e seleziona Disable webhook o Enable webhook. La pagina del webhook mostra lo stato Enabled o Disabled.
• API: chiama Aggiorna un webhook con {"enabled": false} o {"enabled": true}.

Mentre un webhook è disattivato, i nuovi eventi non vengono messi in coda per quel webhook e le richieste già in attesa di un nuovo tentativo vengono messe in pausa. Gli eventi che si verificano mentre è disattivato non vengono consegnati in seguito; se ti servono, leggili con l’API degli eventi. Emailit disattiva anche automaticamente i webhook dopo 3 giorni di errori; vedi Nuovi tentativi ed errori.

Se elimini un webhook, tutti i suoi eventi in attesa vengono scartati.

Ruota il secret

Ruota il secret se potrebbe essere trapelato, o come normale misura di sicurezza.

• Pannello: apri il menu delle azioni, seleziona Webhook secret, poi Reset. Il nuovo secret viene mostrato una sola volta.
• API: chiama Ruota il secret di firma. La risposta contiene il nuovo secret. Anche Recupera un webhook restituisce il secret attuale.

Il vecchio secret smette subito di funzionare e ogni richiesta successiva, compresi i nuovi tentativi di eventi precedenti, viene firmata con quello nuovo. Per ruotarlo senza rifiutare richieste, fai accettare al tuo endpoint entrambi i secret per qualche minuto, reimposta il secret, distribuisci il nuovo valore, poi rimuovi quello vecchio.

Verifica che funzioni

1. Invia un evento di test e conferma che il tuo endpoint restituisce 2xx.
2. Invia un’email reale, o provoca l’evento che hai sottoscritto.
3. Nella scheda Requests del webhook, la richiesta risulta Delivered. L’orario Last used del webhook si aggiorna.

Vedi anche