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

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

• 426 Upgrade Required (RFC 2817) : Il client dovrebbe cambiare il protocollo ed usare ad esempio il TLS/1.0. 449 Retry With Estensione di Microsoft: The request should be retried after doing the appropriate action.

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

Se l'errore che ricevi è HTTP response code is 500, it must be 200, l'errore 500 indica che il webhook aggiunto non è raggiungibile.
Il codice status HTTP 500 è una risposta di errore generica. Significa che il server ha riscontrato una condizione inaspettata che gli ha impedito di soddisfare la richiesta, ovvero che il server non è raggiungibile.
​

Per maggiori informazioni su come viene calcolato il costo, visita la pagina dedicata alle tariffe.