Configurare un webhook

Un webhook è un indirizzo sul tuo server a cui 2Mail invia un messaggio non appena succede qualcosa a un'e-mail: consegnata, rimbalzata, aperta. Così il tuo e-commerce o il tuo CRM sa in pochi secondi che cosa è successo a un messaggio, senza che tu debba guardare il pannello.

Che cosa ti serve

• un indirizzo sul tuo server raggiungibile via https e in grado di ricevere richieste; un webhook senza cifratura non viene accettato
• un pezzo di codice dietro quell'indirizzo che elabori i dati
• diritti di amministratore nel tuo account 2mail

Passo 1: creare il webhook

1. Apri nel pannello la sezione dei webhook e creane uno nuovo.
2. Inserisci l'indirizzo del tuo endpoint.
3. Scegli gli eventi che vuoi ricevere: consegna, bounce, apertura, o una combinazione. Comincia dai bounce — è l'evento su cui devi agire più in fretta.
4. Salva. Il pannello mostra una chiave segreta con cui ogni chiamata viene firmata. Conservala nella configurazione della tua applicazione.

Passo 2: verificare la firma

Chiunque può mandare una richiesta al tuo indirizzo. Ogni chiamata di 2Mail porta perciò una firma nell'intestazione, calcolata con la chiave segreta sul contenuto. Ricalcola quella firma dalla tua parte e rifiuta le richieste in cui non corrisponde. Non saltare questo passo: senza controllo un estraneo può far credere al tuo sistema che un messaggio abbia fatto bounce.

Passo 3: rispondere in fretta

Rispondi subito con un codice di stato della serie 200 ed elabora i dati dopo, per esempio tramite una coda. Se la tua elaborazione dura troppo o rispondi con un errore, 2Mail considera la chiamata fallita e riprova più tardi. Fa' in modo che il tuo codice possa ricevere due volte lo stesso messaggio senza azioni doppie: usa l'identificativo del messaggio per riconoscere le ripetizioni.

Passo 4: provare

Invia un messaggio di prova a un indirizzo che gestisci e guarda se la consegna arriva al tuo endpoint. Per un bounce prova con un indirizzo sicuramente inesistente su un dominio che invece esiste. Il pannello mostra per ogni webhook le ultime chiamate, con la risposta del tuo server — lì vedi subito se il tuo endpoint ha restituito qualcosa di diverso da un 200.

Che cosa farne

• Con un hard bounce segnare l'indirizzo nel tuo CRM, così un commerciale non continua a usarlo.
• Con una consegna mostrare nello storico ordini che la conferma è arrivata — risparmia telefonate.
• Con un'apertura pianificare un'attività di seguito, per esempio dopo un preventivo.

Dove si sbaglia

• Nessuna chiamata — l'indirizzo è raggiungibile solo internamente, oppure un firewall blocca le richieste dall'esterno.
• La firma non torna mai — la calcoli su un contenuto modificato; usa il contenuto grezzo della richiesta.
• Azioni doppie — il tuo endpoint risponde troppo lentamente e riceve quindi ripetizioni.

I webhook fanno parte dell'e-mail API; creare una chiave API è il primo passo se anche la tua applicazione vuole inviare.

Non ci riesci?

Comunicaci tramite contatto l'indirizzo del tuo endpoint e l'ora della prova. Ti mostriamo che cosa ci ha risposto il tuo server.