Webhook in uscita
I webhook sono meccanismi che permettono ad Acumbamail di comunicare con una piattaforma online di tua proprietà. In sostanza, ciò che devi fare è fornire un URL in grado di leggere i dati che Acumbamail gli invierà quando si verificano determinati eventi. Puoi scegliere quali eventi vuoi ricevere, in modo da generare meno carico sul tuo server.
Puoi utilizzare i webhook con uno qualsiasi dei nostri piani a pagamento.
In questo articolo
A cosa servono i webhook
I webhook hanno molte utilità: la principale è mantenere la sincronizzazione tra il tuo database e Acumbamail. Possono anche essere utilizzati per avere più informazioni sull’engagement delle tue email nel tuo CRM, salvando informazioni su quali clienti aprono le tue email. In sostanza sono l’opposto di un’API: in un’API puoi effettuare chiamate per far sì che si verifichino determinate azioni. In un webhook riceverai chiamate quando si verificano determinate azioni. Devi soltanto creare un URL nel tuo sistema web che ti permetta di ricevere gli eventi che Acumbamail invierà.
Esistono due tipi di webhook: quelli per email transazionali e quelli utilizzati per l’invio di campagne. Nel caso delle campagne, il webhook verrà configurato per ciascuna delle liste, poiché possono provenire da database diversi, permettendo così di configurare vari webhook per una campagna, uno per ciascuna delle liste a cui verrà inviata tale campagna. I webhook che si attivano nel caso delle email transazionali verranno configurati per l’intero account. Di seguito trovi un elenco degli eventi che potrai ricevere nei tuoi webhook; non è obbligatorio sceglierli tutti, potrai ricevere solo quelli di tuo interesse. Nella tabella è indicato anche quali webhook funzionano esclusivamente nel servizio campagne e quali in quello di email transazionale.
| Evento | Si attiva quando | Campagne | Email transazionale |
| Iscrizione | Un iscritto si iscrive a una lista. | Sì | No |
| Disiscrizione | Un iscritto si disiscrive da una lista | Sì | No |
| Hard bounce | Viene inviata un’email a un indirizzo che non esiste | Sì | Sì |
| Reclamo | Un destinatario contrassegna un’email come posta indesiderata | Sì | Sì |
| Apertura | Un destinatario apre un’email | Sì | Sì |
| Clic | Un destinatario fa clic su un’email | Sì | Sì |
Configurare webhook per le liste
Per configurare un webhook in una lista devi andare al menu delle liste all’interno di Email e scegliere una delle tue liste. Una volta all’interno della lista, devi andare alla scheda Avanzate.
L’opzione webhook sarà disattivata per impostazione predefinita; fai clic su Configura per iniziare il processo. Una volta fatto, apparirà la pagina che ti permetterà di configurare gli eventi che verranno inviati al tuo URL di elaborazione dei webhook. La pagina è questa:
Qui devi inserire l’URL del tuo sistema che elaborerà i webhook; sarà lo stesso per tutti gli eventi e dovrai selezionare gli eventi che vuoi ricevere. Una volta fatto, puoi attivare o disattivare il webhook quando vuoi utilizzando il pulsante seguente. Tieni presente che questo webhook funzionerà solo per gli iscritti appartenenti alla lista, quindi devi configurarlo in ciascuna delle liste che vuoi sincronizzare.
Configurare webhook per email transazionali
Per configurare i webhook per l’email transazionale, vai alla sezione SMTP del menu a sinistra e, una volta espanso SMTP, devi selezionare l’opzione Webhook:
Una volta fatto, vedrai una pagina molto simile a quella delle liste, che ti permetterà di inserire l’URL del tuo sistema che elaborerà il webhook e, successivamente, selezionare gli eventi che verranno inviati a tale URL e attivare il webhook:
Tieni presente che nel servizio di email transazionale gli eventi che riceverai sono meno, poiché gli eventi di Iscrizione e Disiscrizione dell’iscritto non hanno senso in questo servizio, non essendoci iscritti.
Come elaborare un webhook
Quando si verifica un evento, verrà effettuata una chiamata all’URL che hai configurato, una richiesta POST. Questo URL deve essere preparato per ricevere gli eventi, che verranno inviati in formato JSON e saranno inclusi nel corpo della richiesta che effettueremo. Devi tenere presente che, se il volume dei tuoi invii è elevato, riceverai un gran numero di richieste su quell’URL, quindi deve essere preparato per ricevere correttamente gli eventi. Questo oggetto JSON può contenere da uno a molti eventi, che saranno quelli verificatisi dall’invio della richiesta precedente, e avrà la seguente forma:
Per ogni evento ci sono una serie di informazioni rilevanti. Di seguito includiamo le informazioni contenute in ogni tipo di evento:
Iscrizione
| Parametro | Valore | |
| event | subscribes | |
| L’email dell’iscritto | ||
| timestamp | Data in formato UNIX timestamp (in secondi) | |
| list_id | Identificatore univoco della lista a cui è stato iscritto |
|
| subscriber_fields | Dizionario in formato JSON con i campi del disiscritto. Es., {"email": example@example.com, "name": "Mike"} |
|
|
|
|
|
Disiscrizione
| Parametro | Valore | |
| event | unsubscribes | |
| L’email dell’iscritto disiscritto | ||
| timestamp | Data in formato UNIX timestamp (in secondi) | |
| campaign_id | Identificatore univoco della campagna da cui si è disiscritto |
|
| list_id | Identificatore univoco della lista da cui è stato disiscritto |
|
| subscriber_fields | Dizionario in formato JSON con i campi del disiscritto. Es., {"email": example@example.com, "name": "Mike"} |
|
|
|
|
|
Consegnato
| Parametro | Valore |
|
| event | delivered |
|
| L’email dell’iscritto |
|
|
| timestamp | Data in formato UNIX timestamp (in secondi) |
|
|
|
|
|
Hard Bounce
| Parametro | Valore |
| event | hard_bounces |
| l’email dell’iscritto | |
| timestamp | Data in formato UNIX timestamp (in secondi) |
| bounce_reason | Fornisce il motivo per cui si è verificato l’errore |
|
|
|
Soft Bounce
| Parametro | Valore |
| event | soft_bounces |
| l’email dell’iscritto | |
| timestamp | Data in formato UNIX timestamp (in secondi) |
|
|
|
Reclamo
| Parametro | Valore |
| event | complaints |
| L’email dell’iscritto | |
| timestamp | Data in formato UNIX timestamp (in secondi) |
|
|
|
Apertura
| Parametro | Valore |
| event | opens |
| L’email dell’iscritto | |
| timestamp | Data in formato UNIX timestamp (in secondi) |
|
|
|
Clic
| Parametro | Valore |
| event | clicks |
| L’email dell’iscritto | |
| timestamp | Data in formato UNIX timestamp (in secondi) |
|
|
|