Ce fac webhook-urile
Un webhook se abonează la un anumit eveniment din magazin. Când acel eveniment are loc, Storeep trimite imediat datele evenimentului către un URL specificat de tine (API) sau către o adresă de e-mail specificată (E-mail). Webhook-urile sunt folosite frecvent pentru integrări de urmărire a comenzilor, sincronizări CRM, conversii pe platforme de reclame și notificări automate.
Pentru a gestiona webhook-urile, mergi la Settings → Webhooks. Ai nevoie de permisiunea settings pentru a vedea sau modifica webhook-urile.
Limite pentru webhook-uri
- Maximum 20 de webhook-uri per magazin. Dacă încerci să adaugi al 21-lea, vei primi eroarea "You have reached the maximum of 20 webhooks per store".
- Lista afișează webhook-urile de la cel mai nou la cel mai vechi, paginată la 40 pe pagină.
Crearea unui webhook
Apasă Add new webhook, completează câmpurile de mai jos, apoi apasă Add.
Activate
Bifat implicit. Când este bifat, webhook-ul devine activ imediat ce îl salvezi și evenimentele potrivite sunt trimise. Debifează pentru a salva webhook-ul dezactivat, fără să primească nimic. Poți schimba oricând această stare editând webhook-ul.
Name
- Obligatoriu. Maximum 50 de caractere.
- O etichetă descriptivă afișată în listă, de exemplu Facebook CAPI order created.
Type
- API: Storeep trimite un request HTTP POST cu datele evenimentului către URL-ul tău.
- E-mail: Storeep trimite un e-mail cu datele evenimentului către adresa ta.
Event
Evenimentul din magazin care declanșează webhook-ul. Există trei evenimente:
- Session created: o nouă sesiune de vizitator este creată în magazinul tău.
- Order created: o nouă comandă este plasată.
- Order updated: statusul sau datele unei comenzi existente se modifică.
Important: tipul E-mail livrează doar Order created și Order updated. Dacă alegi E-mail cu Session created, webhook-ul se salvează dar nu trimite nimic. Folosește tipul API dacă ai nevoie de evenimentul de sesiune.
Format
Există o singură opțiune, Json: payload-ul este trimis ca document JSON.
URL (doar pentru tipul API)
- Obligatoriu când tipul este API. Maximum 500 de caractere.
- Câmpul afișează un prefix
https://pentru tine, deci introdu doar host-ul și calea, de exempluapi.example.com/events/order. Dacă inserezi o adresă completă cuhttps://sauhttp://, prefixul este eliminat înainte de salvare. - Placeholder-e dinamice: poți injecta orice câmp din datele evenimentului în URL folosind sintaxa cu două acolade
{{field_name}}. Exemplu:example.com/postback?cid={{fbclid}}&payout={{order_total}}. Valorile sunt codate URL, iar un placeholder fără câmp existent va fi gol. Astfel poți trimite date de conversie direct către o platformă de reclame fără proxy. - Adresa este validată după eliminarea placeholder-elor, deci un URL invalid va returna "The url you have entered is incorrect".
Adresa de e-mail (doar pentru tipul E-mail)
- Obligatoriu când tipul este E-mail. Trebuie să fie o adresă validă, maximum 127 de caractere.
Editarea unui webhook
Apasă pe orice rând pentru a deschide editorul. Orice câmp poate fi modificat. Câmpul URL se pre-umple doar când tipul salvat este API, iar câmpul de e-mail doar când tipul salvat este E-mail. Apasă Save pentru a aplica. Salvarea cu Activate debifat dezactivează webhook-ul fără a-l șterge.
Coloanele listei de webhook-uri
- Name: eticheta cu data creării.
- URL / E-mail: destinația.
- Type: API sau E-mail.
- Event: Session created, Order created sau Order updated.
- Format: Json.
- Status: Activated sau Deactivated.
Ștergerea unui webhook
Selectează unul sau mai multe rânduri și apasă Delete webhooks. Ștergerea este permanentă și oprește orice livrare viitoare pentru acea subscriere.
Livrare, retry-uri și e-mailuri de eroare
Această secțiune se aplică webhook-urilor de tip API. Webhook-urile E-mail sunt trimise o singură dată, fără retry și fără urmărirea eșecurilor.
Comportamentul retry
- Fiecare request are un timeout de 5 secunde. Dacă destinația returnează o eroare 5xx, 429 (rate limited) sau nu poate fi accesată (eroare de conexiune), livrarea este tratată ca eșec temporar și se retrimite.
- Dacă prima livrare eșuează, Storeep retrimite cu backoff exponențial, până la 5 retry-uri: aproximativ după 30s, 60s, 120s, 240s, apoi 480s. După ultimul retry, evenimentul este abandonat.
- Un răspuns 4xx altul decât 429 (de exemplu 404 sau 403) este tratat ca eșec permanent. Storeep nu retrimite, deoarece un endpoint greșit sau care respinge nu se va repara singur.
- Când ai mai multe webhook-uri pe același eveniment, retry-ul retrimite doar către cele care au eșuat. Destinațiile care au răspuns deja cu succes sunt sărite, deci nu vei primi livrări duplicate.
E-mail de notificare a eșecului
- Storeep numără livrările eșuate consecutiv pentru fiecare webhook. După 5 eșecuri consecutive, proprietarul magazinului primește un e-mail cu titlul "Action needed: your Storeep webhook is failing", în limba proprietarului, cu numele webhook-ului, destinația, evenimentul și ultimul cod de status HTTP.
- Primești exact un e-mail pentru fiecare serie de eșecuri. Nu se trimit alte e-mailuri până când acel webhook nu se recuperează.
- Imediat ce o livrare reușește din nou, contorul de eșecuri se resetează la zero și notificarea se reactivează, astfel încât o viitoare serie de eșecuri să poată trimite din nou e-mail.
Sfaturi și capcane
- Poți crea mai multe webhook-uri pentru același eveniment, de exemplu să trimiți Order created atât către un CRM, cât și către o platformă de reclame, ca două intrări separate.
- Dacă endpoint-ul tău necesită autentificare, pune un token în query string-ul URL-ului, fie hardcodat, fie printr-un
{{placeholder}}din datele evenimentului, sau folosește un proxy care adaugă autentificarea înainte de forward. - Session created se declanșează pentru fiecare sesiune unică de vizitator și poate avea volum mare în magazinele aglomerate. Abonează-te doar dacă endpoint-ul tău poate gestiona traficul și ține minte că funcționează doar cu tipul API.