Sari la conținutul principal

Cum configurezi webhook-urile și verifici logurile

Un webhook, adică o notificare automată trimisă între sisteme, face o cerere către un sistem extern când în magazin are loc un eveniment, de exemplu crearea unei comenzi sau aprobarea unui review. Logurile păstrează rezultatul fiecărei livrări și te ajută să identifici erorile fără să retrimiți manual datele.

Ai nevoie de un webhook dacă un sistem de gestiune (ERP), un serviciu de curierat sau o altă integrare trebuie să primească automat un eveniment imediat după ce acesta are loc.

Permisiunea necesară

Crearea, testarea și administrarea webhook-urilor necesită permisiunea pentru setările magazinului. Stabilește evenimentul, adresa și formatul datelor împreună cu integratorul sistemului destinatar.

Pentru primul test, folosește un singur eveniment și o adresă HTTPS de test controlată și aprobată de integratorul sistemului destinatar. Activează webhook-ul, trimite cererea de test, apoi verifică răspunsul în log și rezultatul în sistemul extern. Păstrează webhook-ul activ pentru evenimente reale numai după ce integratorul sistemului destinatar confirmă rezultatul.

Cererea de test ajunge efectiv la serviciul extern. Cât timp webhook-ul este activ, pot fi trimise și evenimente reale de același tip; programează testul împreună cu echipa care administrează sistemul extern.

Creează un webhook​

  1. Accesează Setari > API si webhook-uri > Webhook-uri.
  2. Apasă Adauga webhook.
  3. Completează Denumire interna cu un nume care identifică destinația și scopul.
  4. Selectează evenimentul care trebuie să declanșeze trimiterea.
  5. Completează endpointul, adică adresa HTTPS la care MerchantPro trebuie să trimită cererea.
  6. În Mai multe optiuni, configurează transformarea payloadului (conținutul trimis în corpul cererii), headerele HTTP (metadatele cererii) sau numărul de reîncercări numai dacă integrarea le cere. Câmpul pentru reîncercări acceptă valori între zero și trei; valoarea implicită este trei.
  7. Apasă Salveaza.

Lista evenimentelor disponibile este generată din funcționalitățile active ale magazinului. Pentru descrierea payloadurilor și a fiecărui eveniment, consultă documentația webhook-urilor.

Protejează datele trimise

Payloadul poate conține date despre clienți, comenzi sau produse. Folosește numai o adresă controlată de partenerul aprobat și nu distribui secretul de semnare sau conținutul logurilor în spații publice.

Testează livrarea​

  1. În lista Webhook-uri, activează webhook-ul.
  2. Deschide acțiunile definiției și apasă Trimite cerere de test.
  3. Confirmă trimiterea și verifică mesajul afișat de MerchantPro.
  4. Deschide Loguri webhook pentru rezultatul cererii.

Sistemul destinatar trebuie să răspundă cu un cod HTTP din familia 2xx. Un cod diferit, depășirea timpului de așteptare (timeout) sau o problemă de conectare este înregistrată ca livrare eșuată.

De exemplu, dacă webhook-ul urmărește crearea unei comenzi, un răspuns 204 la cererea de test apare ca livrare reușită. Un răspuns 500 sau lipsa unui răspuns până la timeout apare ca livrare eșuată și trebuie investigată înainte de activarea fluxului real.

Verifică logurile​

Pagina de loguri este deschisă pentru webhook-ul selectat. Poți căuta după identificatorul tehnic al cererii (Request ID) sau codul HTTP și poți filtra după status și interval de timp.

Deschide o livrare pentru a verifica:

  • adresa, evenimentul și statusul livrării;
  • codul HTTP și durata;
  • Request ID-ul, util pentru identificarea livrării în MerchantPro și pentru o eventuală solicitare către echipa de suport MerchantPro;
  • payloadul și headerele trimise;
  • corpul răspunsului primit de la destinație;
  • dacă înregistrarea provine dintr-o livrare reală sau dintr-un test.

Dacă livrarea eșuează sau webhook-ul se dezactivează​

  1. Deschide ultima livrare și verifică adresa, codul HTTP, durata și corpul răspunsului.
  2. Notează data și ora livrării, plus valoarea headerului X-Webhook-Event, apoi caută în sistemul destinatar cererea din același interval. Compară rezultatul cu codul HTTP din logul MerchantPro.
  3. Confirmă împreună cu integratorul sistemului destinatar headerele, verificarea semnăturii și formatul payloadului.
  4. Trimite din nou o cerere de test și confirmă un răspuns 2xx înainte să reactivezi fluxul real.

MerchantPro dezactivează automat webhook-ul după 8 livrări reale consecutive care rămân eșuate după reîncercările configurate. O livrare reală reușită resetează numărătoarea, iar cererile de test nu o modifică. Corectează mai întâi problema la destinație, apoi reactivează definiția.

Dacă logul arată un răspuns de eroare primit de la destinație, trimite integratorului sistemului destinatar denumirea internă a webhook-ului, data și ora testului, valoarea X-Webhook-Event și codul HTTP. Dacă cererea nu apare corect în loguri sau statusul înregistrat de MerchantPro nu corespunde testului, contactează echipa de suport MerchantPro și indică Request ID-ul, dacă este disponibil.

Administrează definiția și secretul​

Din listă poți modifica statusul, edita definiția, deschide logurile sau șterge webhook-ul. Definițiile create și controlate de o aplicație instalată sunt vizibile, dar nu pot fi editate, dezactivate sau șterse manual; administrează aplicația asociată.

Secretul de semnare al webhook-urilor create de comerciant poate fi copiat prin acțiunea Copiază secretul de semnare. Sistemul destinatar trebuie să îl folosească pentru verificarea autenticității cererilor. Webhook-urile controlate de aplicații folosesc secretul aplicației, conform documentației tehnice.

Verifică rezultatul​

  • Evenimentul ales corespunde acțiunii pe care vrei să o urmărești.
  • Cererea de test apare în loguri.
  • Destinația răspunde cu un cod 2xx.
  • Payloadul nu include mai multe date decât are nevoie integrarea.
  • Webhook-ul rămâne activ după livrările reale.
Citește și