Cosa sono i webhook e come configurarli in Sendcloud? – Sendcloud Help Center

Scopo: impara le basi dei webhook e come puoi configurarli nel tuo pannello Sendcloud.

Per utilizzare i webhook devi connetterti a Sendcloud tramite un'API. Per maggiori informazioni sulla connessione con la nostra API, ti invitiamo a consultare la nostra Documentazione API.

Per ulteriori informazioni sui webhook di Sendcloud, consulta la sezione Webhooks nella nostra documentazione API.

Per il supporto ai webhook specifico per l'integrazione, consulta il nostro articolo: Miglioramento della sicurezza e del supporto all'integrazione dei webhook. Copre la configurazione dei webhook per diverse integrazioni e le migliori pratiche per proteggere i tuoi webhook.

Cosa sono i webhook?

I webhook permettono alle applicazioni di comunicare tra loro in "tempo reale". Un altro modo in cui le applicazioni possono comunicare è tramite un'API. A differenza di un'API che funziona con il polling, un webhook riceve i dati non appena l'applicazione li gestisce. Non è necessario fare alcuna richiesta perché si tratta di un processo automatico. Pertanto non devi preoccuparti di un ritardo nella comunicazione.

API: un'API recupera periodicamente i dati dall'applicazione facendo una richiesta. Un'API esegue un'azione specifica solamente quando riceve una richiesta.

Webhook: un webhook non estrae i dati ma li riceve dall'applicazione non appena si verificano. Gli webhook invece eseguono azioni solo quando vengono soddisfatti determinati criteri.

Esempio: ricezione di aggiornamenti sul tracking da Sendcloud

(Vedi l'immagine qui sotto come riferimento)

Quando ricevi un aggiornamento sul tracking tramite l'API, la procedura è la seguente:
La tua applicazione cerca di prelevare i dati di tracking da Sendcloud a intervalli. Lo farà anche quando non sono disponibili nuovi dati.
Quando vuoi ricevere aggiornamenti sul tracking tramite un webhook, la procedura è la seguente:
Sendcloud invia gli aggiornamenti di tracking alla tua applicazione non appena sono disponibili in Sendcloud.

Webhook di Sendcloud

Webhook Integration Object: questo webhook entra in gioco quando una nuova integrazione API viene aggiunta a Sendcloud. Si attiva quando un'integrazione API viene collegata, cancellata o aggiornata. Clicca qui per vedere cosa contiene il payload di questo webhook.

Webhook Parcel Status Changed Object: questo webhook entra in gioco quando lo stato di un pacco cambia; non importa quale sia il cambiamento di stato. Clicca qui per vedere cosa c'è nel payload di questo webhook.

Webhook Return Created Object: Questo webhook viene attivato quando un reso viene creato tramite API o il Portale dei resi. Clicca qui per visualizzare i dettagli del payload.

Come impostare i webhook in Sendcloud?

Per fare in modo che Sendcloud comunichi attivamente gli aggiornamenti dei pacchi (ad esempio gli aggiornamenti del tracking), devi creare un endpoint API. Ogni volta che si verifica un aggiornamento, Sendcloud farà una richiesta attraverso quell'endpoint. Per maggiori informazioni, consulta la sezione Webhooks nella nostra documentazione API.

Copia l'url del webhook dalla tua applicazione
Vai nel tuo pannello Sendcloud e apri le impostazioni dell'integrazione andando su Impostazioni > Integrazioni > Configura
Seleziona la casella Feedback Webhook abilitato
Trova il campo Webhook url (vedi immagine sotto) e incollaci l'url del tuo webhook
Prova il tuo webhook cliccando sul pulsante Webhook API di prova
Clicca su Salva

Fatto! Il tuo webhook è ora configurato e il payload dovrebbe iniziare ad arrivare alla tua applicazione. Puoi usarlo per impostare dei trigger che portano a determinate azioni. Un esempio potrebbe essere quello di collegare le tue e-mail di tracking agli aggiornamenti di tracking in arrivo. In questo modo potrai fornire aggiornamenti istantanei ai tuoi clienti.

Per i resi, riceverai gli aggiornamenti via webhook solo se la spedizione in uscita è stata creata tramite l'integrazione API.

FAQ

Se configuro un webhook, a quali pacchi si applica?

I webhook sono configurati per integrazione. Ciò significa che il webhook si applicherà solo ai pacchi creati tramite l’integrazione per la quale è stato configurato. I pacchi creati tramite altre integrazioni o metodi non attiveranno questo webhook.

Perché il mio URL del webhook restituisce un errore 404 o risulta irraggiungibile?

Problema: L’URL del webhook non è corretto (ad esempio errore di digitazione, dominio errato o HTTPS mancante) oppure l’endpoint non è accessibile pubblicamente.

Esempi:

404 Not Found

DNS resolution failed

Soluzione: Controlla attentamente la sintassi dell’URL e il dominio. Assicurati che l’endpoint sia pubblicamente raggiungibile e utilizzi HTTPS con un certificato SSL/TLS valido.

Perché ricevo errori di certificato SSL/TLS con il mio webhook?

Problema: L’endpoint utilizza un certificato scaduto, autofirmato o configurato in modo errato.

Esempi:

SSL Handshake failed

Unable to verify certificate

Soluzione: Installa un certificato SSL valido da un’autorità di certificazione (CA) affidabile, rinnova i certificati scaduti e verifica che i certificati intermedi siano installati correttamente.

Perché le richieste del mio webhook scadono o non ricevono risposta?

Problema: Il server che riceve il webhook è troppo lento o non risponde affatto.

Esempi:

 Request timed out

 Connection reset

Soluzione: Assicurati che il server risponda entro il limite di timeout, ottimizza il codice per un’elaborazione più rapida oppure sposta le operazioni più pesanti su processi in background. Controlla anche eventuali firewall o limiti di velocità (rate limiting).

Perché il mio webhook restituisce errori HTTP come 405 o 500?

Problema: L’endpoint si aspetta un metodo HTTP specifico oppure non restituisce una risposta corretta.

Esempi:

405 Method Not Allowed

500 Internal Server Error

Soluzione: Assicurati che l’endpoint accetti richieste POST, restituisca un codice di stato 2xx in caso di ricezione riuscita e che gli errori vengano registrati e gestiti correttamente.

Perché l’autenticazione o la verifica della firma del mio webhook fallisce?

Problema: Il provider del webhook firma le richieste, ma l’endpoint non le verifica correttamente o utilizza chiavi errate.

Esempi:

401 Unauthorized

403 Forbidden

Soluzione: Implementa la verifica HMAC o della firma utilizzando la chiave segreta corretta e assicurati che gli header e il payload vengano analizzati esattamente come inviati.

Perché il payload del mio webhook è invalido o formattato in modo errato?

Problema: Il webhook invia dati in formato JSON (o altri formati), ma il server ricevente non riesce a interpretarli correttamente.

Esempi:

400 Bad Request

Unexpected token in logs

Soluzione: Verifica che il Content-Type sia supportato (di solito application/json), valida e registra il payload e aggiorna il codice dell’endpoint per supportare nuovi campi o formati.

Perché alcune richieste del mio webhook vengono limitate o ignorate?

Problema: L’endpoint riceve troppe richieste e inizia a rifiutarne alcune.

Esempi:

429 Too Many Requests

Requests delayed or silently failing

Soluzione: Aggiungi una coda o un sistema di limitazione (throttling) per gestire i picchi di traffico, implementa nuovi tentativi (retry) con backoff esponenziale e monitora o ridimensiona le risorse del server quando necessario.

Clicca qui per andare alla nostra guida alle API di Sendcloud e vedere il payload del webhook.