Webhook în WooCommerce: configurare, semnătură și test

Webhookurile pot reduce nevoia de a întreba permanent magazinul dacă există modificări. Ele nu elimină însă duplicatele, întreruperile sau schimbarea ordinii în care ajung mesajele. O implementare robustă trebuie să se comporte corect și când aceeași informație este primită de două ori sau când receptorul este temporar indisponibil.

Exemplele din acest ghid sunt demonstrative. Nu trimite comenzi reale, date personale sau secrete de integrare către colectoare publice pentru teste. Folosește un mediu autorizat și obiecte sintetice. Pentru dezvoltarea unui receptor personalizat, configurația și politica de procesare trebuie documentate înainte de activarea pe magazinul live.

Webhook versus API: cine pornește cererea?

Într-o integrare bazată pe interogare periodică, clientul cere date la intervale stabilite. Într-un webhook, sistemul care observă evenimentul trimite notificarea. WooCommerce permite configurarea unor astfel de notificări pentru resurse și evenimente documentate. ^[1] Alegerea mecanismului trebuie să urmeze nevoia de actualizare, volumul și capacitatea receptorului.

Nu este obligatoriu să alegi exclusiv unul. Un webhook poate anunța că un obiect s-a schimbat, iar o cerere autorizată prin REST API poate verifica starea curentă. Această combinație poate ajuta reconcilierea, dar trebuie proiectată astfel încât notificările repetate să nu provoace o avalanșă de cereri suplimentare.

Într-un exemplu ipotetic, notificarea unei modificări de comandă pornește verificarea, dar emiterea facturii are loc numai după validarea stării comerciale potrivite. Evenimentul tehnic și decizia afacerii nu sunt același lucru. Numele unui topic nu înlocuiește regulile privind plata, anularea sau returul.

Definește contractul înainte să creezi webhookul

Scrie ce eveniment este urmărit, ce sistem îl primește, ce obiect trebuie identificat și ce operație poate rezulta. Definește și ce nu trebuie să se întâmple. De exemplu, o modificare a adresei nu trebuie să creeze automat o a doua comandă în ERP, iar un mesaj repetat nu trebuie să reducă stocul încă o dată.

Documentează identificatorii folosiți în ambele sisteme. Numărul afișat clientului poate diferi de cheia internă a comenzii. Pentru variante, identificatorul produsului părinte poate fi insuficient. Organizarea catalogului și a stocurilor este relevantă înainte de automatizare, deoarece datele ambigue nu devin clare prin transmitere mai rapidă.

Include în contract timpii acceptabili și politica de eroare. Un receptor poate accepta rapid un mesaj și să îl proceseze ulterior într-o coadă. În acel caz, interfața trebuie să distingă „primit” de „aplicat”. Nu folosi aceeași etichetă verde pentru două niveluri diferite de confirmare.

Configurează un webhook într-un mediu controlat

În WooCommerce, documentația plasează administrarea webhookurilor în setările avansate. Alegi numele, starea, topicul, adresa de livrare și secretul. Verifică instrucțiunile pentru versiunea instalată și testează mai întâi cu receptorul pregătit. ^[1] Nu activa o notificare către o adresă pe care nu o controlezi sau care redirecționează imprevizibil.

Numele configurației ar trebui să explice scopul, de exemplu „Comenzi test către receptor intern”. Nu pune secretul în nume. Folosește HTTPS și confirmă că certificatul și domeniul receptorului sunt corecte. Verificarea HTTPS este o condiție de transport, nu o dovadă că mesajul aparține magazinului autorizat.

Pentru primul test, creează un obiect demonstrativ și notează ora, identificatorul și evenimentul așteptat. Nu porni simultan toate topicurile posibile. Un set mic permite înțelegerea payloadului și a frecvenței înainte să expui receptorul la volumul operațional.

Verifică semnătura pe corpul original al cererii

Implementarea WooCommerce documentează o semnătură bazată pe HMAC-SHA256, codificată Base64, pentru payloadul livrat. ^[2] Receptorul trebuie să folosească secretul corespunzător și exact octeții primiți. Dacă decodezi JSON-ul și îl serializezi din nou înainte de verificare, poți schimba corpul și obține altă semnătură.

Exemplul următor verifică doar calculul și comparația. Nu este un endpoint complet și nu trebuie publicat singur ca soluție de securitate. Corpul brut, antetul și secretul trebuie obținute de codul serverului, cu limite de dimensiune, acces la configurație și tratarea erorilor. Nu tipări secretul în răspuns sau jurnal.

function verify_wc_signature(string $rawBody, string $signature, string $secret): bool {
    if ($secret === '' || $signature === '') {
        return false;
    }
    $expected = base64_encode(hash_hmac('sha256', $rawBody, $secret, true));
    return hash_equals($expected, $signature);
}

PHP oferă funcțiile folosite pentru HMAC și comparația sigură a valorilor. ^{[3] [4]} Semnătura validă demonstrează concordanța mesajului cu secretul, nu unicitatea operației și nici faptul că starea comercială este cea potrivită. Aceste verificări trebuie făcute separat.

Acceptarea mesajului trebuie legată de o salvare durabilă

O arhitectură propusă pentru procese lente este: verificare, validare minimă, salvare în coadă, confirmare de primire și procesare ulterioară. Dacă răspunzi cu succes înainte de salvare și procesul se oprește, poți pierde informația. Dacă execuți sincron o operație grea, poți depăși timpul disponibil al cererii.

Acesta este un model de proiectare, nu o garanție implicită a oricărui plugin WooCommerce. Receptorul trebuie să confirme ce a persistat și să expună starea ulterioară. O coadă păstrată doar în memoria procesului nu oferă aceleași proprietăți ca o înregistrare durabilă care poate fi reluată după repornire.

Definește limite de dimensiune și de volum. Un mesaj prea mare sau cu structură invalidă trebuie tratat explicit, nu lăsat să consume resurse necontrolat. Nu extrage adrese arbitrare din payload pentru a le solicita automat fără validare; o integrare trebuie să aibă destinații și operații bine delimitate.

Duplicatele cer idempotență, nu speranță

Idempotența înseamnă, în acest context, că repetarea aceleiași operații nu produce efectul comercial de mai multe ori. Un identificator de livrare poate ajuta la recunoașterea unei cereri, dar cheia afacerii trebuie să țină cont de obiect și de tipul modificării. Nu confunda două actualizări legitime ale aceleiași comenzi cu un duplicat.

Un exemplu propus: receptorul înregistrează evenimentul și operația aplicată, iar crearea facturii verifică dacă documentul corespunzător există deja. O reluare după timeout citește rezultatul înainte să încerce o nouă creare. Politica exactă depinde de sistemul țintă și trebuie să evite două procese concurente care fac aceeași verificare simultan.

Pentru sincronizarea cu ERP, această regulă este mai importantă decât dispariția rapidă a sarcinii din interfață. O coadă goală nu dovedește lipsa duplicatelor, la fel cum o sarcină încă în așteptare nu dovedește eșecul dacă există o reluare programată și un motiv clar.

Ordinea notificărilor și starea curentă

Proiectează receptorul pentru posibilitatea ca două mesaje să ajungă într-o ordine diferită de cea a modificărilor. Verifică versiunea sau momentul obiectului acolo unde contractul permite și citește starea curentă când decizia o cere. Nu lăsa o notificare mai veche să inverseze automat o stare nouă fără o regulă explicită.

Într-un scenariu ipotetic, comanda este actualizată, apoi anulată. Dacă primul mesaj este procesat mai târziu, integrarea nu ar trebui să reactiveze comanda doar pentru că acel payload a ajuns ultimul. Decizia trebuie luată din regulile obiectului și din sursa de adevăr, nu din ordinea întâmplătoare a conexiunilor.

Documentează cine deține fiecare stare. Magazinul poate fi sursa pentru comandă, procesatorul pentru confirmarea plății, iar sistemul logistic pentru livrare. Niciun webhook izolat nu trebuie transformat într-o confirmare pentru toate cele trei domenii.

Reîncercări, pauze și escaladare

Un incident temporar trebuie să lase o sarcină identificabilă și o politică de reluare. Un payload invalid cere însă revizie, nu încercări infinite. Separă eroarea de transport de refuzul comercial și afișează operatorului ce acțiune este sigură. Nu șterge mesajul doar pentru a face raportul să arate curat.

Monitorizează starea webhookului în WooCommerce și jurnalele relevante. Platforma documentează tratarea livrărilor eșuate și posibilitatea dezactivării după eșecuri repetate; verifică configurația efectivă. ^[1] Nu presupune că un webhook creat o dată va continua să livreze indiferent de răspunsurile receptorului.

Un worker periodic verificat poate procesa coada receptorului dacă aceasta este proiectată în acest sens. Creșterea frecvenței nu repară un secret greșit și poate agrava o problemă de capacitate. Înainte de reluare masivă, repară cauza și testează un lot mic.

Matricea de teste înainte de activare

Adaugă și testul concurenței: două mesaje primite aproape simultan. Un mecanism verificat numai secvențial poate eșua când doi workeri încearcă aceeași operație. Criteriul de acceptanță trebuie să privească rezultatul comercial, nu doar numărul răspunsurilor HTTP.

Jurnale utile fără date sensibile inutile

Înregistrează identificatorul operației, ora, topicul, codul răspunsului și starea procesării. Păstrează payloadul complet numai când există un motiv și controale adecvate. Pentru raportarea unui incident, o urmă anonimizată poate fi suficientă; nu trimite întregul istoric de comenzi către terți pentru o verificare banală.

Inspectarea răspunsurilor HTTP și verificarea structurii JSON pot susține diagnosticul folosind exemple curate. Pentru integrări multiple, separă sursele în jurnal, astfel încât un eveniment venit dintr-un marketplace să nu fie confundat cu o actualizare manuală din magazin.

Rotirea secretului fără întreruperi neexplicate

Stabilește în avans procedura de schimbare a secretului. Cine îl generează, unde este salvat și când devine activ în receptor? Dacă modifici numai una dintre părți, semnăturile vor fi refuzate. Acest rezultat este corect din perspectiva verificării, dar poate opri fluxul comercial dacă echipa nu a planificat tranziția.

O tranziție controlată poate include o fereastră scurtă și documentată de schimbare, oprirea alocărilor noi sau o politică explicită de acceptare temporară a cheii anterioare. Alegerea depinde de receptor și de cerințele de securitate. Nu păstra chei vechi la nesfârșit „ca să meargă” și nu dezactiva verificarea semnăturii pe durata unei probleme.

După schimbare, testează un eveniment sintetic și confirmă că vechea configurație nu mai este acceptată după încheierea tranziției. Revizuiește și accesul persoanelor care au cunoscut secretul. Jurnalul trebuie să arate că verificarea a trecut sau a eșuat, nu valoarea cheii folosite.

Separă mediul de test de operațiunile reale

O copie a magazinului poate păstra setările integrării și poate trimite notificări către receptorul de producție dacă nu este izolată. Înainte de teste, verifică adresele de livrare, cheile, identificatorii mediului și orice acțiune care poate emite documente sau anunța un curier. Datele demonstrative nu sunt suficiente dacă destinația rămâne un sistem real.

Folosește o identitate clară a mediului în configurația internă și verifică potrivirea ei la receptor atunci când arhitectura permite. Nu o trata ca înlocuitor al autenticității, ci ca protecție suplimentară împotriva greșelilor de configurare. Două medii care trimit aceiași identificatori către aceeași destinație pot produce coliziuni greu de diagnosticat.

În exemplul unei facturări, testul trebuie să se oprească înainte de emiterea documentului real sau să folosească mediul de test documentat al furnizorului. Nu anula ulterior documente doar pentru a compensa un test făcut fără izolare. Proiectează dovada necesară astfel încât să verifici integrarea fără efecte comerciale nedorite.

Reconcilierea descoperă ce nu vezi în jurnalul livrărilor

O verificare periodică între sursă și destinație poate identifica obiecte lipsă sau stări divergente. Aceasta nu trebuie să recreeze tot catalogul și nici să suprascrie automat orice diferență. Definește intervalul, obiectele vizate și regula după care alegi sursa de adevăr pentru fiecare câmp.

De exemplu, o comandă poate exista în ambele sisteme, dar transportul poate fi confirmat numai într-unul. Raportul trebuie să arate diferența și acțiunea permisă. Nu transforma orice abatere într-o nouă creare de comandă. Reconcilierea este un control al rezultatului, distinct de faptul că un mesaj a fost expediat cu succes.

La finalul unui incident, raportează numărul obiectelor verificate, remediate și rămase pentru analiză. Păstrează o urmă a modificărilor și evită concluzia „totul este sincronizat” dacă ai verificat numai un subset. Această precizie ajută operatorul să știe ce mai trebuie urmărit și previne repetarea inutilă a intervenției asupra obiectelor deja corecte.

Include și un responsabil pentru alertele de procesare. Un jurnal disponibil, dar neverificat, nu este suficient pentru operațiuni critice. Definește ce incident cere intervenție, ce poate fi reîncercat automat și ce trebuie confirmat manual. Nu permite reluarea în masă a acțiunilor financiare sau logistice numai pe baza faptului că receptorul a revenit online.

Un test de revenire trebuie să confirme și că mesajele deja aplicate nu sunt procesate din nou ca operații noi. Păstrează registrul de idempotență și istoricul necesar atunci când repornești workerul. Golirea cozii și ștergerea dovezilor nu sunt același lucru cu remedierea incidentului.

Întrebări frecvente

Semnătura validă elimină duplicatele?

Nu. Ea verifică autenticitatea și integritatea în raport cu secretul. Prevenirea efectelor duplicate cere o regulă separată, persistentă și testată inclusiv în condiții de concurență.

Pot trimite payloaduri reale către un colector public?

Nu este o practică potrivită pentru teste care pot conține date personale sau secrete. Folosește obiecte sintetice și un receptor controlat, cu acces și păstrare a datelor limitate.

Surse și documentație

Procedurile propuse și exemplele numerice sunt editoriale și ipotetice, nu rezultate măsurate pentru clienți. Afirmațiile despre platforme sunt susținute de documentația indicată; verifică versiunea și configurația proiectului înainte de intervenții în producție.

1. WooCommerce: configurarea și administrarea webhookurilor
2. WooCommerce: implementarea WC_Webhook și semnătura
3. PHP: calculul HMAC
4. PHP: comparație sigură a semnăturilor