Webhook
Impostazioni per i webhook in uscita: configurare e testare gli endpoint per gli eventi di spedizioni e tour, nonché impostare un'e-mail di avviso in caso di consegna non riuscita.
Nella scheda Webhook delle impostazioni si configurano i webhook in uscita. Con i webhook, X4fleet segnala automaticamente determinati eventi – come le modifiche di stato di spedizioni o tour – a un sistema esterno (ad esempio un sistema ERP o cliente). Non appena si verifica un evento configurato, X4fleet invia i dati associati all'indirizzo memorizzato (URL). Questa scheda è destinata agli amministratori che collegano X4fleet a sistemi di terze parti.
Nota: Tutte le modifiche in questa scheda vengono applicate insieme alle altre impostazioni tramite il pulsante per il salvataggio delle impostazioni.
1. Navigazione
La scheda Webhook si trova all'interno delle Impostazioni, nella barra delle schede della pagina delle impostazioni.
Alcune opzioni (ad esempio l'applicazione tra gruppi) sono visibili solo se ci si trova nel gruppo principale.
2. E-mail di avviso in caso di consegna non riuscita
Affinché non si perdano dati senza accorgersene, X4fleet può inviare automaticamente un'e-mail di avviso in caso di invio di un webhook non riuscito.
Attivare l'e-mail di avviso
- Attivare la casella di controllo «E-mail di avviso attiva».
- Nel campo «E-mail di avviso», inserire l'indirizzo del destinatario a cui inviare la notifica.
- Salvare le impostazioni.
Se in seguito la consegna di un webhook non riesce, l'indirizzo memorizzato riceve un messaggio di avviso corrispondente.
Applicare ai sottogruppi
Se ci si trova nel gruppo principale, è disponibile anche l'opzione «Applicare ai sottogruppi». Quando è attivata, la configurazione dell'e-mail di avviso si applica anche ai gruppi subordinati.
Modificare il modello dell'e-mail di avviso
È possibile adattare il contenuto dell'e-mail di avviso in più lingue. Tramite l'editor di testo si modifica il modello nelle lingue disponibili. Con i pulsanti di inserimento dell'editor è possibile inserire segnaposto (variabili) nel testo, che durante l'invio vengono sostituiti automaticamente con i rispettivi valori.
Nota: Mantenere aggiornato il modello in tutte le lingue necessarie, affinché i destinatari ricevano il messaggio di avviso nella lingua corretta.
3. Endpoint webhook per spedizioni e tour
Nella scheda sono disponibili due elenchi separati:
- Webhook delle spedizioni – endpoint che vengono attivati in caso di eventi relativi alle spedizioni.
- Webhook dei tour – endpoint che vengono attivati in caso di eventi relativi ai tour.
In entrambi gli elenchi è possibile aggiungere, configurare, testare e rimuovere un numero qualsiasi di endpoint.
Aggiungere un endpoint
- Nell'elenco desiderato (spedizioni o tour), fare clic sul pulsante «+».
- Una nuova riga vuota viene aggiunta all'elenco.
- Configurare la riga come descritto nella sezione 4.
- Salvare le impostazioni.
Rimuovere un endpoint
Tramite l'icona di rimozione della rispettiva riga si elimina nuovamente un endpoint dall'elenco. Salvare quindi le impostazioni affinché la modifica abbia effetto.
4. Configurazione di un endpoint
Ogni endpoint webhook viene configurato tramite una propria riga con i seguenti campi:
| Campo | Descrizione |
|---|---|
| Attivo | Attiva o disattiva l'endpoint. Solo gli endpoint attivi vengono attivati. |
| Attivo per i sottogruppi | Applica l'endpoint anche ai gruppi subordinati (visibile solo nel gruppo principale). |
| Modalità pull | Commuta tra il funzionamento push e pull. In modalità pull, il campo URL viene nascosto, poiché non avviene alcun invio attivo a un indirizzo di destinazione. |
| URL | L'indirizzo di destinazione a cui X4fleet invia i dati (solo quando la modalità pull è disattivata). |
| Includere le spedizioni | Include i dati delle spedizioni nel payload trasmesso. |
| Includere i punti di trasporto | Include i punti di trasporto (punti di ritiro/consegna). |
| Escludere le spedizioni parziali non rilevanti | Esclude le spedizioni parziali non rilevanti derivanti dalle suddivisioni. |
| Trigger | Selezione multipla degli stati in cui il webhook viene attivato (stato della spedizione o stato del tour). |
| Tipo di contenuto della richiesta | Formato dei dati trasmessi (Content-Type della richiesta). |
| Codificare il payload come stringa | Trasmette il payload come stringa codificata. |
| Formato data/ora | Definizione del formato per le indicazioni di data e ora nel payload. |
| Nome utente | Nome di accesso per l'autenticazione sul sistema di destinazione. |
| Password | Password per l'autenticazione sul sistema di destinazione. |
| Certificato | Certificato per una connessione sicura al sistema di destinazione. |
Tramite il campo Trigger si stabilisce a quali modifiche di stato l'endpoint viene richiamato. Per i webhook delle spedizioni sono disponibili gli stati delle spedizioni, per i webhook dei tour gli stati dei tour.
Nota: Il campo URL viene visualizzato solo quando la modalità pull è disattivata. Attivare la modalità pull se il sistema di destinazione recupera autonomamente i dati invece di riceverli da X4fleet.
5. Testare un endpoint
Prima di utilizzare un endpoint in produzione, è possibile testarlo direttamente dalla riga.
- Configurare la riga con i valori desiderati (in particolare URL e credenziali di accesso).
- Fare clic sul pulsante «Testa webhook» della rispettiva riga.
- X4fleet invia una richiesta di test all'indirizzo configurato e mostra il risultato.
In questo modo si verifica se l'indirizzo di destinazione è raggiungibile e se l'autenticazione funziona correttamente, senza dover attendere un evento reale.
6. Salvare
Tutte le configurazioni di questa scheda – le impostazioni dell'e-mail di avviso così come gli endpoint delle spedizioni e dei tour – vengono salvate insieme alle altre impostazioni. Le modifiche hanno effetto solo dopo il salvataggio.
Nota: Gli endpoint aggiunti o rimossi così come i valori dei campi modificati si applicano solo dopo che le impostazioni sono state salvate.