Come faccio a connettere i Webhook?

I Webhook sono la soluzione perfetta per ricevere informazioni in tempo reale. ShippyPro ti offre la possibilità di ricevere etichette, aggiornamenti di tracking e messaggi di errore per gli ordini quasi istantaneamente.

Sommario:

1. Connettere il tuo Webhook

2. Errori e Risoluzioni

Scopri di più sulle nostre API nella nostra Documentazione API:

1. Connettere il tuo Webhook

• Per prima cosa, vai a Integrazioni & API > API e fai click su Aggiungi Webhook.

• Quindi inserisci l'URL del server in cui desideri ricevere tutte le informazioni per l'Evento o gli Eventi specifici che sceglierai dall'elenco sotto.

• Potrai scegliere tra: Ordine Spedito, Errore Ordine e Aggiornamenti di Tracking.

• A questo punto, inserisci il Nome Utente e la Password per l'autenticazione Webhook lato server. Attenzione: l'autenticazione non è un passaggio obbligatorio, se il tuo server non lo prevede puoi decidere di non includerlo.

• Una volta incluso, decidi se abilitare l'opzione Riprova in caso il Webhooks fallisca. Puoi anche impostare il numero massimo di nuovi tentativi fino a 10 volte.

• Infine decidi se applicare una Custom Header: di cosa stiamo parlando? Le Custom Header ti danno la possibilità di autenticare le tue richieste Webhook e rifiutare quelle che non contengono queste intestazioni personalizzate.

• Attiva questa opzione per avere una misura di sicurezza aggiuntiva.

• Imposta una Key e una Value dell'Header per completare il setup.

• Quando il tuo Webhook sarà connesso, puoi Modificarlo, Eliminarlo o Testarlo.

• Cliccando su Test sarai in grado di visualizzare tutte le informazioni trasmesse:

{

"Event": "TRACKING_UPDATE",

"tracking": "WZ116539070",

"date": 1622671204,

"message": "Shipment delivered,

"city": "Florence",

"est_delivery_date": "0",

"first_status_date": "1622152801",

"late": "0",

"code": 6,

"OrderID": "24957298",

"TransactionID": "48572_1",

"TrackingCarrier": "FedEx",

"MarketplaceID": "0",

"MarketplacePlatform": "Manual shipment",

"ExternalLink": "",

"FromAddressCompany": "John Doe srl.",

"ToAddressCompany": "",

"FromAddressCountry": "IT",

"ToAddressCountry": "IT"

}

• Mentre facendo click su Visualizza Log Webhook troverai un elenco di tutti i tuoi Log.

• Per filtrarli per Endpoint, Evento, Risultato o Nuovo tentativo dovrai solo fare click sui filtri specifici.

Ecco i dati che sarai in grado di consultare da questa sezione:

Data

Data Fine

Order ID

Transaction ID

Carrier

Endpoint

Event

Risultato

Nuovo tentativo

Tempo impiegato

Richiesta

Risposta

Attraverso i Webhook Logs, inserendo il tuo endpoint riceverai una notifica delle modifiche allo stato di consegna e potrai accedere a utili informazioni sugli aggiornamenti del tracking.

2. Errori e Troubleshooting

Posso avere più di un Webhook?

Certo, segui questi passaggi per farlo:

• Nella barra laterale clicca su API > API.

• Nella sezione Webhook clicca su Aggiungi Webook.

• Quando si apre il pop up aggiungi tutte le informazioni necessarie e Salva.

Sto collegando i webhook e ricevo "La risposta HTTP deve essere in formato JSON. Riprovare" nella risposta

Di solito, l'errore compare se il tipo di contenuto della risposta non è stato impostato come application/json. È necessario assicurarsi che la risposta sia formattata come application/json o, in alternativa, restituire un 204 come codice HTTP e nessun corpo della risposta.

Durante l'invio di un webhook verso il mio server ricevo questa risposta:{"success":false,"reason":"CSRF token mismatch"}

Questo è un errore solitamente causato da un firewall che ha bloccato la ricezione del webhook.

Assicurarsi di aver rimosso il blocco verso i nostri ip e provare ad effettuare una nuova chiamata API.

In generale, il test del webhook passa solo se:

codice HTTP compreso tra 200 e 300 + risposta in json

oppure

Codice HTTP 204 (nessun risultato) e risposta non json

Qual è l'indirizzo IP pubblico utilizzato per gli aggiornamenti dei webhook?

I webhook arrivano da un IP casuale, quindi nel caso in cui vogliate impostare un indirizzo IP statico sarà necessario un ulteriore preventivo da parte del nostro reparto vendite. Contattateci all'indirizzo sales@shippypro.com

HTTP response code is 403, it must be 200. Please Retry!

L'errore 403 significa che la richiesta è valida ma il tuo server si rifiuta di accettare la nostra richiesta di creazione (l'autenticazione non ha effetto).

Una volta risolto il problema di autenticazione per l'endpoint indicato, ti potrai correttamente connettere al webhook.

Qual è il significato di ogni status?

Di seguito la lista dei vari stati che potresti ricevere insieme ai loro significati:

• 1xx Informational : Richiesta ricevuta, continua l’elaborazione.

• 100 Continue : Il server ha ricevuto l’header della richiesta e il client deve procedere ad inviare il corpo della richiesta (solitamente nelle richieste di tipo POST).

• 101 Switching Protocols : Il richiedente ha richiesto di cambiare il protocollo in uso e il server è a conoscenza di ciò che dovrà fare.

• 102 Processing

2xx Success : L’azione è stata ricevuta con successo, compresa ed accettata.

• 200 OK : Risposta standard per le richieste HTTP andate a buon fine.

• 201 Created

• 202 Accepted : La richiesta di elaborazione è stata accettata ma non è ancora terminata.

• 203 Non-Authoritative Information

• 204 No Content

• 205 Reset Content

• 206 Partial Content

• 207 Multi-Status : In caso di risposte XML, quando più azioni possono essere richieste, i dettagli dei singoli stati sono dati nel corpo della risposta. Vedi WebDAV (RFC 4918) per le specifiche associate.

• 208 Already Reported

• 226 IM Used

3xx Redirezione : Il client deve eseguire ulteriori azioni per soddisfare la richiesta.

• 300 Multiple Choices

• 301 Moved Permanently : Questa è tutte le future richieste andranno dirette ad un altro URI (specificato nell’header Location).

• 302 Found : Questo è il codice più usato ma anche un classico esempio di non aderenza agli standard nella pratica quotidiana. Infatti, le specifiche di HTTP/1.0 (RFC 1945) richiederebbero che il client esegua redirezioni temporanee (la descrizione originale era “Moved Temporarily”), ma i più diffusi browser l’hanno implementata come 303 descritta di seguito. Perciò, HTTP/1.1 ha aggiunto i codici di stato 303 e 307 per distinguere tra i due comportamenti. Comunque, la maggior parte delle applicazioni e dei framework web ancora usano il codice di stato 302 come se fosse il 303.

• 303 See Other (da HTTP/1.1) : La risposta alla richiesta può essere trovata sotto un’altra URI usando il metodo GET.

• 304 Not Modified

• 305 Use Proxy (da HTTP/1.1) : Molti client HTTP (come Mozilla ed Internet Explorer) non gestiscono correttamente le risposte con questo codice di stato.

• 306 Switch Proxy : Non più usato.

• 307 Temporary Redirect (da HTTP/1.1) : In quest’occasione, la richiesta dovrebbe essere ripetuta con un’altra URI, ma successive richieste possono essere ancora dirette a quella originale. In contrasto con 303, la richiesta di POST originale deve essere reiterata con un’altra richiesta di tipo POST.

• 308 Permanent Redirect

4xx Client Error : La richiesta è sintatticamente scorretta o non può essere soddisfatta.

• 400 Bad Request : La richiesta non può essere soddisfatta a causa di errori di sintassi.

• 401 Unauthorized : Simile a 403/Forbidden, ma pensato per essere usato quando l’autenticazione è possibile ma è fallita o non può essere fornita.

• 402 Payment Required : L’intendimento originale prevedeva un suo utilizzo per realizzare meccanismi di digital cash/micropagamento, ma questo non si è mai verificato ed il codice non è mai stato utilizzato.

• 403 Forbidden : La richiesta è legittima ma il server si rifiuta di soddisfarla. Contrariamente al codice 401 Unauthorized, l’autenticazione non ha effetto.

• 404 Not Found : La risorsa richiesta non è stata trovata ma in futuro potrebbe essere disponibile.

• 405 Method Not Allowed : La richiesta è stata eseguita usando un metodo non permesso. Ad esempio questo accade quando di usa il metodo GET per inviare dati da presentare con un metodo POST.

• 406 Not Acceptable

• 407 Proxy Authentication Required

• 408 Request Timeout : Il tempo per inviare la richiesta è scaduto e il server ha terminato la connessione.

• 409 Conflict

• 410 Gone : Indica che la risorsa richiesta non è più disponibile e non lo sarà più in futuro.

• 411 Length Required : La richiesta non specifica la propria dimensione come richiesto dalla risorsa richiesta.

• 412 Precondition Failed

• 413 Request Entity Too Large : La richiesta è più grande di quanto il server possa gestire.

• 414 Request-URI Too Long : L’URI richiesto è troppo grande per essere processato dal server.

• 415 Unsupported Media Type : L’entità della richiesta è di un tipo non accettato dal server o dalla risorsa richiesta.

• 416 Requested Range Not Satisfiable

• 417 Expectation Failed

• 418 I’m a teapot : Questo è un tipico pesce d’aprile dell’ITEF (RFC 2324). Non si aspettano implementazioni in alcun server HTTP.

• 421 Misdirected Request : indirizzo errato

• 422 Unprocessable Entity : entità non processabile

• 423 Locked

• 424 Failed Dependency

5xx Server Error : Il server ha fallito nel soddisfare una richiesta apparentemente valida.

• 500 Internal Server Error : Messaggio di errore generico senza alcun dettaglio.

• 501 Not Implemented : Il server non è in grado di soddisfare il metodo della richiesta.

• 502 Bad Gateway

• 503 Service Unavailable : Il server non è al momento disponibile. Generalmente è una condizione temporanea.

• 504 Gateway Timeout

• 505 HTTP Version Not Supported : Il server non supporta la versione HTTP della richiesta.

• 506 Variant Also Negotiates

• 507 Insufficient Storage

• 508 Loop Detected

• 509 Bandwidth Limit Exceeded : Questo codice di stato, benché usato da molti server, non è un codice di stato ufficiale in quanto non è specificato in alcuna RFC.

• 510 Not Extended

• 511 Network Authentication Required

• 599 Network Connect Timeout Error