Webhook in entrata
Dalla sezione Integrazioni (visibile solo per gli account a pagamento), potrai configurare una serie di webhook in entrata. Questi costituiscono un canale aggiuntivo per integrare sistemi esterni con Acumbamail in modo rapido e semplice. Di seguito sono riportate tutte le informazioni su come configurare e utilizzare questo tipo di webhook.
In questo articolo:
- Che cos’è un webhook in entrata?
- Creare un nuovo webhook in entrata
- Aggiornare ed eliminare un webhook in entrata
- Passaggi per realizzare l’integrazione
Che cos’è un webhook in entrata?
Un webhook in entrata è un tipo di integrazione che consente di chiamare Acumbamail da qualsiasi altro sistema esterno per eseguire un’operazione.
Dato un determinato insieme di operazioni, potrai sceglierne una ed eseguirla in modo semplice effettuando una richiesta HTTP di tipo POST a un URL dedicato generato per cliente e per operazione. Questa richiesta dovrà includere nel corpo i dati necessari per poter eseguire l’operazione, in formato JSON.
Webhook in entrata vs. API
Se un’operazione è disponibile tramite API e tramite un webhook in entrata, dovrai configurare l’integrazione solo tramite una delle due modalità, poiché l’effetto sarà identico. Entrambe ti permetteranno la stessa cosa: chiamare Acumbamail affinché venga eseguita una determinata operazione. Tuttavia, la differenza sta nel modo in cui viene realizzata l’integrazione, come riassunto nella seguente tabella:
| Caratteristica | Webhook in entrata | API |
| Autenticazione | È trasparente. Non è necessario aggiungere nulla alla richiesta, poiché l’URL da chiamare viene generato in modo esclusivo per cliente e operazione. | È necessario aggiungere manualmente l’auth_token dell’account in ogni richiesta per poter effettuare l’autenticazione. |
| Chiamata | Viene generato un URL diverso per cliente e operazione. È necessario effettuare una richiesta HTTP POST a tale URL. | Ogni operazione ha un URL fisso e comune a tutti i clienti. A questo URL si possono effettuare richieste HTTP POST o GET. |
| Payload | Puoi inviare direttamente un JSON generato dal sistema esterno, poiché durante la configurazione del webhook potrai mappare i campi presenti nel JSON ricevuto e i campi richiesti dall’operazione. | Il sistema che effettua la chiamata deve preparare un payload con un formato specifico richiesto dall’operazione. |
| Facilità di integrazione | Non richiede competenze di programmazione. Molti sistemi consentono di configurare automazioni in cui l’utente deve solo inserire un URL, e il sistema si occupa di effettuare la chiamata passando un JSON con informazioni specifiche. | È più complesso e può richiedere competenze di programmazione, poiché è necessario adattare le informazioni inviate insieme alla richiesta a un formato specifico. |
|
|
|
|
Creare un nuovo webhook in entrata
Una volta effettuato l’accesso alla vista principale di Webhook in entrata, è necessario fare clic sul pulsante Nuovo webhook. Si aprirà un popup in cui potrai configurare i dettagli del tuo webhook:
- Nome: Un nome per identificare il webhook.
- Endpoint: Qui troverai l’elenco delle operazioni disponibili, tra le quali dovrai sceglierne una.
- Payload in entrata: Dovrai copiare un JSON di esempio generato dal sistema esterno che effettuerà la chiamata, poiché servirà da riferimento per poter configurare la mappatura dei campi.
- Attivato/Disattivato: Dato un webhook in entrata, affinché Acumbamail accetti la chiamata associata a quel webhook, questo dovrà essere attivo. Se per qualche motivo non vuoi eliminare il webhook ma desideri disabilitarlo temporaneamente, puoi scegliere di contrassegnarlo come non attivo (utile, ad esempio, se ritieni che l’URL possa essere stato compromesso).
- Mappatura dei campi: Verranno elencati tutti i parametri di input necessari per poter eseguire l’operazione. Dato in precedenza un payload di esempio (che sarà il JSON generato dal sistema esterno), avrai a disposizione un selettore in cui sono inclusi tutti i nodi presenti nel JSON, in modo da poter scegliere quale nodo contiene le informazioni associate a ciascun parametro.
Quando avrai inserito tutte le informazioni, puoi fare clic sul pulsante Crea per salvare il nuovo webhook in entrata.
Una volta creato il webhook, devi seguire alcuni semplici passaggi affinché la tua integrazione sia pronta e operativa.
Che cos’è il payload in entrata?
Il payload in entrata è costituito dai parametri o dai dati che il sistema esterno invierà ad Acumbamail quando chiamerà l’URL di integrazione. Questi parametri conterranno le informazioni di interesse a seconda del tipo di endpoint o operazione selezionata.
Come posso conoscere il payload in entrata?
Questo dipende dal sistema esterno che vuoi integrare con Acumbamail. Alcuni consentono di visualizzare un esempio delle informazioni che verranno inviate o persino di configurare diverse opzioni per formattare i dati che verranno inviati nella richiesta. Tuttavia, altri non forniscono direttamente queste informazioni.
Nel caso in cui ti risulti difficile ottenere un esempio dei parametri di input che verranno inviati dal sistema da cui sarà effettuata la chiamata ad Acumbamail, puoi utilizzare un servizio come WebhookSite. Questo genera un URL di test che potrai chiamare dal tuo sistema esterno e ti permetterà di visualizzare i parametri ricevuti nella chiamata di prova. Una volta visualizzati i parametri, potrai copiarli e incollarli nel campo "payload in entrata" in Acumbamail.
Infine, con il webhook in entrata già creato in Acumbamail, dovrai solo modificare l’integrazione che hai configurato in precedenza nel sistema esterno, affinché invece di chiamare l’URL di test chiami l’URL reale fornito da Acumbamail.
Se non ti è ancora chiaro come configurarlo, puoi inserire come payload in entrata quanto segue: {"email": ""} e mappare solo questo campo con il campo email della tua lista. Una volta fatto, forza una chiamata al webhook (inviando il tuo modulo con dati di prova) e contatta il nostro team di supporto. Potranno esaminare le informazioni reali ricevute nella chiamata al webhook e indicarti esattamente come deve essere configurato il campo "payload in entrata".
Che formato deve avere il payload in entrata?
Le informazioni devono essere inviate in formato JSON.
Formato JSON
Se i dati vengono inviati in formato JSON, dovrai solo copiare un esempio dei parametri inviati con la chiamata nel campo "payload in entrata" e, una volta copiato, selezionare nella sezione "mappatura dei campi" quali nodi del JSON corrispondono ai parametri di input attesi, a seconda dell’operazione scelta.
Formato x-www-form-urlencoded da Elementor
Se utilizzerai il webhook in entrata da Elementor, devi tenere presente quanto segue:
- Usa WebhookSite come spiegato nella sezione precedente per vedere cosa invierà Elementor.
- Non devi copiare la sezione "Raw Content", bensì quella di "Form values", che è quella con il formato atteso, includendo però anche i campi "form", "fields" e "meta".
Per il seguente esempio:
Il campo "payload in entrata" in Acumbamail dovrebbe risultare nel seguente modo:
{
"form": { "id": "4abdd65", "name": "test" },
"fields": { "name": { "id": "name", "type": "text", "title": "Nome", "value": "test", "raw_value": "test", "required": "0" }, "email": { "id": "email", "type": "email", "title": "Email", "value": "test@test.com", "raw_value": "test@test.com", "required": "1" } },
"meta": { "name": { "id": "1", "year": "2" } }
}
Operazioni disponibili
In questa sezione sono descritte le operazioni accessibili tramite webhook in entrata.
Se hai bisogno di un’operazione aggiuntiva presente nell’API ma non come webhook in entrata, puoi contattare il team di supporto e richiederne l’inclusione. La tua richiesta sarà valutata e la nuova operazione potrebbe essere aggiunta.
Aggiungere un iscritto a una lista
Questa operazione consente, data una lista specifica, di aggiungervi un iscritto.
Campi richiesti
Questi sono i campi associati all’operazione:
| Nome | Obbligatorio | Tipo atteso | Descrizione |
| Sì | Testo | L’indirizzo email dell’iscritto. | |
| double_optin | No | Booleano (0,1) Per impostazione predefinita 0 | Indica se inviare o meno l’email di conferma dell’iscrizione alla lista. |
| welcome_email | No | Booleano (0,1) Per impostazione predefinita 0 | Indica se inviare o meno l’email di benvenuto all’iscritto. |
| update_subscriber | No | Booleano (0,1) Per impostazione predefinita 0 | Indica se aggiornare o meno le informazioni dell’iscritto se questo esiste già nella lista. |
|
|
|
|
|
Bisogna tenere presente che questa operazione richiede un passaggio aggiuntivo, tramite il quale il webhook viene associato a una lista specifica. Apparirà un selettore aggiuntivo in cui potrai scegliere una delle tue liste.
Questo è necessario perché ogni lista ha campi diversi che definiscono i suoi iscritti. Questi campi (oltre a quelli propri dell’operazione) devono essere anch’essi mappati durante la configurazione del webhook in entrata, per sapere in quale nodo specifico del JSON ricevuto si può trovare l’informazione di ciascun campo. Così, potrai osservare che quando scegli una lista diversa, i campi disponibili nella sezione Mappatura dei campi, vengono aggiornati aggiungendo i campi propri della lista.
Eliminare un iscritto da una lista
Questa operazione consente di eliminare un iscritto da una lista.
Campi richiesti
Questi sono i campi associati all’operazione:
| Nome | Obbligatorio | Tipo atteso | Descrizione |
| Sì | Testo | L’indirizzo email dell’iscritto. | |
| list_id | Sì | Numero intero | L’identificatore della lista a cui appartiene l’iscritto. |
|
|
|
|
Annullare l’iscrizione di un iscritto da una lista
Questa operazione consente di contrassegnare come disiscritto un iscritto da una lista.
Campi richiesti
Questi sono i campi associati all’operazione:
| Nome | Obbligatorio | Tipo atteso | Descrizione |
| Sì | Testo | L’indirizzo email dell’iscritto. | |
| list_id | Sì | Numero intero | L’identificatore della lista a cui appartiene l’iscritto. |
|
|
|
|
|
Inviare un’email transazionale
Questa operazione consente di inviare un’email a un iscritto specifico.
Campi richiesti
Questi sono i campi associati all’operazione:
| Nome | Obbligatorio | Tipo atteso | Descrizione |
| body | Sì | Testo | Il contenuto dell’email. |
| category | No | Numero intero | La categoria dell’invio. |
| to_email | Sì | Testo | L’indirizzo email del destinatario. |
| from_email | Sì | Testo | L’indirizzo email del mittente. |
| bcc_email | No | Testo | L’indirizzo email in copia nascosta. |
| subject | Sì | Testo | L’oggetto dell’email. |
|
|
|
|
|
Inviare una campagna con template
Questa operazione consente di creare e inviare una campagna a una o più liste, scegliendo uno dei tuoi template personalizzati come contenuto.
Campi richiesti
Questi sono i campi associati all’operazione:
| Nome | Obbligatorio | Tipo atteso | Descrizione |
| name | Sì | Testo | Il nome interno della campagna. |
| from_name | Sì | Testo | Il nome del mittente. |
| from_email | Sì | Testo | L’indirizzo email del mittente. |
| subject | Sì | Testo | L’oggetto dell’email. |
| lists | Sì | Un elenco di numeri interi | L’elenco degli identificatori delle liste destinatari. |
| template_id | Sì | Numero intero | L’identificatore del template che verrà utilizzato come contenuto dell’email. |
|
|
|
|
|
Mappatura del campo lists
Si evidenzia qui il caso speciale del campo "lists". In questo campo bisogna passare l’identificatore della lista o delle liste destinatari della campagna. Nel caso in cui siano più liste, il JSON ricevuto dovrà contenere una chiave con una serie di identificatori in formato elenco.
Tuttavia, durante la creazione del webhook in entrata, nel campo Payload in entrata, dovrai copiare il tuo JSON aggiungendo le virgolette all’elenco. In questo modo il nodo che contiene le liste sarà interpretato come un nodo finale che contiene un valore e non come un nodo intermedio. Di seguito viene presentato un JSON di esempio (potrebbe avere qualsiasi altro formato) per illustrarlo:
| JSON ricevuto nella richiesta quando si invoca l’URL |
|
Payload in entrata (copiare con virgolette) |
| { "data": { "name": "My campaign", "from": "Me", "email": "my.email@company.com", "subject": "My subject", "template": 1111, "lists": [2222, 2223] } } |
|
{ "data": { "name": "My campaign", "from": "Me", "email": "my.email@company.com", "subject": "My subject", "template": 1111, "lists": "[2222, 2223]" } } |
|
|
|
|
Valori di ritorno
In risposta a una richiesta ricevuta, verrà sempre restituito un JSON il cui contenuto dipenderà:
- Dall’operazione richiesta.
- Dal fatto che sia stata eseguita correttamente o che si sia verificato un errore.
Risposta in caso di successo
La seguente tabella riporta lo stato e il contenuto in formato JSON della risposta restituita per ogni operazione quando questa è stata eseguita correttamente.
| Operazione |
|
Stato | JSON |
| Aggiungere iscritto |
|
201 |
|
| Eliminare iscritto |
|
201 |
|
| Annullare iscrizione iscritto |
|
201 |
|
| Inviare email transazionale |
|
200 |
|
| Inviare campagna con template |
|
200 |
|
|
|
|
|
|
Risposta in caso di errore
Per qualsiasi operazione, nel caso in cui non possa essere eseguita, verrà restituito un JSON che includerà un messaggio descrittivo dell’errore sotto la chiave "error". Nella seguente tabella sono inclusi i possibili codici di errore che una chiamata può restituire:
| Stato | Possibile motivo |
| 400 |
|
| 403 |
|
| 404 |
|
|
|
|
Aggiornare ed eliminare un webhook in entrata
Dall’elenco dei webhook in entrata che hai creato, nel menu delle azioni puoi sia aggiornare la configurazione di un webhook sia eliminarlo.
Per aggiornare la configurazione di un webhook, devi solo fare clic sul pulsante Azioni e selezionare l’opzione Modifica. Si aprirà il popup con tutte le informazioni associate al webhook. Qui potrai apportare le modifiche di cui hai bisogno, prima di fare clic sul pulsante Aggiorna per salvare le modifiche.
Per eliminare un webhook, devi solo fare clic sul pulsante Azioni e selezionare l’opzione Elimina. Ricorda che, invece di eliminarlo, puoi anche disattivare un webhook se temporaneamente non ne hai bisogno.
Come realizzare l’integrazione
Una volta creato un webhook in entrata e quando questo è attivo, è il momento di testare l’integrazione.
Dall’elenco dei webhook creati, fai clic sul pulsante Azioni e seleziona l’opzione Copia URL. Questo copierà negli appunti l’URL specifico creato per questo webhook.
Ora non resta che effettuare la configurazione nel sistema esterno che effettuerà la chiamata. Dato l’evento che deve attivare l’operazione in Acumbamail, devi configurarlo nel seguente modo:
- Deve effettuare una richiesta HTTP di tipo POST all’URL che hai appena copiato. L’URL risponderà solo a richieste di tipo POST e HEAD.
- Nel corpo della richiesta deve inviare le informazioni generate, preferibilmente come raw JSON, il cui content type sarà "application/json; charset=utf-8". È supportato anche il content type "application/x-www-form-urlencoded".
Questo è tutto. Puoi provare a effettuare una o più chiamate. Nella vista principale in cui sono elencati tutti i webhook puoi consultare quante chiamate riuscite ed errate sono state registrate, così come l’ora in cui è stata registrata l’ultima chiamata.
Esempio di configurazione e chiamata
Questa sarebbe la configurazione del tuo webhook in entrata, per il caso specifico dell’invio di una campagna con template.
Una volta che il webhook è attivo, viene mostrato un esempio di chiamata utilizzando Postman.
