Cosa fanno i webhook
Un webhook si sottoscrive a un evento specifico del negozio. Quando quell'evento accade, Storeep invia immediatamente i dati dell'evento a un URL che indichi tu (tipo API) o a un indirizzo email che indichi tu (tipo E-mail). I webhook sono comunemente usati per integrazioni di tracciamento ordini, sincronizzazioni con il CRM, conversioni sulle piattaforme pubblicitarie e notifiche automatiche.
Per gestire i webhook, vai su Impostazioni → Webhook. Ti serve il permesso impostazioni per visualizzare o modificare i webhook.
Limiti dei webhook
- Massimo 20 webhook per negozio. Se provi ad aggiungere il 21esimo ricevi l'errore "Hai raggiunto il massimo di 20 webhook per negozio".
- L'elenco mostra i webhook dal più recente, paginati a 40 per pagina.
Creare un webhook
Clicca su Aggiungi nuovo webhook, compila i campi qui sotto, poi clicca su Aggiungi.
Attiva
Selezionato per impostazione predefinita. Quando è selezionato, il webhook è attivo nel momento in cui lo salvi e gli eventi corrispondenti vengono inviati. Deselezionalo per salvare il webhook in stato disattivato, senza che riceva nulla. Puoi cambiare questa impostazione in qualsiasi momento modificando il webhook.
Nome
- Obbligatorio. Massimo 50 caratteri.
- Un'etichetta descrittiva mostrata nell'elenco, per esempio Facebook CAPI ordine creato.
Tipo
- API: Storeep invia una richiesta HTTP POST con i dati dell'evento al tuo URL.
- E-mail: Storeep invia un'email con i dati dell'evento al tuo indirizzo.
Evento
L'evento del negozio che attiva il webhook. Esistono tre eventi:
- Sessione creata: viene creata una nuova sessione visitatore nel tuo negozio.
- Ordine creato: viene effettuato un nuovo ordine.
- Ordine aggiornato: lo stato o i dati di un ordine esistente cambiano.
Importante: il tipo E-mail consegna solo Ordine creato e Ordine aggiornato. Se scegli E-mail con Sessione creata, il webhook si salva ma non invia mai nulla. Usa il tipo API se ti serve l'evento di sessione.
Formato
Una sola opzione, Json: il payload viene inviato come documento JSON.
URL (solo tipo API)
- Obbligatorio quando il tipo è API. Massimo 500 caratteri.
- Il campo mostra per te un prefisso
https://, quindi inserisci solo l'host e il percorso, per esempioapi.example.com/events/order. Se incolli un indirizzohttps://ohttp://completo, il prefisso viene rimosso prima del salvataggio. - Placeholder dinamici: inserisci qualsiasi campo dai dati dell'evento nell'URL con la sintassi a doppia parentesi graffa
{{field_name}}. Esempio:example.com/postback?cid={{fbclid}}&payout={{order_total}}. I valori sono codificati per URL e un placeholder il cui campo è assente si risolve in un valore vuoto. Questo ti permette di inviare i dati di conversione direttamente a una piattaforma pubblicitaria senza un proxy. - L'indirizzo viene convalidato dopo la rimozione dei placeholder, quindi un URL non valido restituisce "L'url che hai inserito non è corretto".
Indirizzo email (solo tipo E-mail)
- Obbligatorio quando il tipo è E-mail. Deve essere un indirizzo valido, massimo 127 caratteri.
Modificare un webhook
Clicca su una qualsiasi riga per aprire l'editor. Ogni campo è modificabile. Il campo URL si precompila solo quando il tipo salvato è API, e il campo email si precompila solo quando il tipo salvato è E-mail. Clicca su Salva per applicare. Salvare con Attiva deselezionato disattiva il webhook senza eliminarlo.
Colonne dell'elenco dei webhook
- Nome: l'etichetta con la sua data di creazione.
- URL / E-mail: la destinazione.
- Tipo: API o E-mail.
- Evento: Sessione creata, Ordine creato o Ordine aggiornato.
- Formato: Json.
- Stato: Attivato o Disattivato.
Eliminare un webhook
Seleziona una o più righe e clicca su Elimina webhook. L'eliminazione è permanente e interrompe tutte le consegne future per quella sottoscrizione.
Consegna, tentativi ed email di errore
Questa sezione riguarda i webhook API. I webhook E-mail sono "invia e dimentica": vengono inviati una sola volta senza tentativi successivi e senza tracciamento degli errori.
Comportamento dei tentativi
- Ogni richiesta ha un timeout di 5 secondi. Se una destinazione restituisce un errore 5xx, 429 (limite di frequenza) o non è raggiungibile (errore di connessione), la consegna è trattata come fallimento temporaneo e ritentata.
- Dopo il primo fallimento della consegna, Storeep ritenta con backoff esponenziale fino a 5 tentativi: circa dopo 30s, 60s, 120s, 240s, poi 480s. Dopo l'ultimo tentativo l'evento viene scartato.
- Una risposta 4xx diversa da 429 (per esempio 404 o 403) è trattata come fallimento permanente. Storeep non la ritenta, perché un endpoint errato o che rifiuta non si correggerà da solo.
- Quando hai più webhook sullo stesso evento, un tentativo reinvia solo a quelli falliti. Gli endpoint che hanno già restituito successo vengono saltati, così non ricevi consegne duplicate.
Email di notifica di errore
- Storeep conta i fallimenti di consegna consecutivi per ogni webhook. Dopo 5 fallimenti consecutivi, l'owner del negozio riceve un'email intitolata "Azione necessaria: il tuo webhook Storeep sta fallendo", nella lingua dell'owner, che elenca il nome del webhook, la destinazione, l'evento e l'ultimo codice di stato HTTP.
- Ricevi esattamente un'email per ogni serie di fallimenti. Non vengono inviate altre email finché quel webhook non si ripristina.
- Non appena una consegna riesce di nuovo, il contatore dei fallimenti si azzera e la notifica si riarma, così una futura serie di errori può inviarti di nuovo un'email.
Consigli e insidie
- Puoi creare più webhook per lo stesso evento, per esempio inviare Ordine creato sia a un CRM sia a una piattaforma pubblicitaria come due voci separate.
- Se il tuo endpoint richiede autenticazione, metti un token nella query string dell'URL, fisso o tramite un
{{placeholder}}dai dati dell'evento, oppure mettilo dietro un proxy che aggiunge l'autenticazione prima di inoltrare. - Sessione creata scatta per ogni sessione visitatore unica e può avere un volume elevato sui negozi affollati. Sottoscrivilo solo se il tuo endpoint regge il throughput, e ricorda che funziona solo con il tipo API.