tecnico · risposta con fonti
Webhook email: cos'è e come implementarlo
Un webhook email è una callback HTTP attivata da un provider di servizi email per notificare eventi specifici a un server di destinazione. Invece di interrogare periodicamente un'API per conoscere lo stato, l'applicazione riceve dal provider un payload JSON o XML inviato a un URL predefinito subito dopo un evento, come un errore di consegna o il clic su un link.
Funzionamento
Quando si verifica un evento, il provider email genera una richiesta HTTP POST. La richiesta contiene un payload con i metadati dell'evento, tra cui l'ID del messaggio, l'indirizzo del destinatario e il timestamp. Il server ricevente deve restare in ascolto su un endpoint pubblico, convalidare la richiesta in arrivo e rispondere con 200 OK per confermarne la ricezione. Se il server restituisce un errore, il provider può ritentare la consegna con una strategia di backoff esponenziale.
Perché conta per chi invia
I webhook sono fondamentali per mantenere la reputazione del mittente. Ricevendo notifiche in tempo reale di hard bounce o segnalazioni di spam, puoi rimuovere automaticamente gli indirizzi non validi dalle tue liste. Così eviti invii ripetuti a caselle inesistenti, uno dei segnali principali che gli ISP usano per classificare un mittente come di bassa qualità. Reagire rapidamente a questi segnali garantisce una deliverability complessiva più alta.
Aspetti operativi
Tra i problemi più comuni ci sono i timeout, quando il server ricevente elabora il payload in modo sincrono. Per evitarli, implementa un'architettura asincrona: il webhook viene ricevuto, messo in coda in un sistema come Redis o RabbitMQ e confermato immediatamente. Anche la sicurezza è fondamentale: i server dovrebbero verificare la firma del provider o controllare l'IP di origine per evitare notifiche di eventi falsificate.
Esempio concreto di implementazione
Un flusso tipico prevede la configurazione di un URL in un provider come Resend o Amazon SES. Quando un utente clicca un link in un'email, il provider invia una richiesta POST a /webhooks/email con un corpo come { event: click, email: user@example.com, link: https://site.com/offer }. L'applicazione aggiorna quindi il record dell'utente nel database per segnare la campagna come riuscita.
Integrazione con gli strumenti
Per configurare i webhook servono un URL pubblico e un modo per testare i payload. Puoi usare SendHQ o i suoi strumenti gratuiti (https://sendhq.cc/tools) per gestire i requisiti tecnici della tua infrastruttura email e assicurarti che la configurazione rispetti gli standard del settore.
Le domande dei team
Qual è la differenza tra un'API e un webhook?
Un'API è una richiesta che il client invia al server per ottenere dati (pull). Un webhook è una richiesta che il server invia al client per trasmettere dati automaticamente (push) quando si verifica un evento.
Come si protegge un endpoint per webhook email?
Usa token segreti nell'intestazione, verifica la firma HMAC fornita dal servizio email oppure limita il traffico in entrata agli intervalli IP del provider.
Cosa succede se il mio server è offline durante un evento webhook?
La maggior parte dei provider professionali mette l'evento in coda e ne ritenta la consegna più volte nell'arco di ore o giorni, prima di contrassegnarlo come non recapitabile.
Fonti primarie
- Documentazione di Resend — Resend
- Documentazione per sviluppatori di Postmark — Postmark
- Guida per sviluppatori di Amazon SES — Amazon Web Services