Ce este un webhook — explicat pentru non-tehnici

Clientul plătește cu cardul. Peste câteva secunde, comanda lui apare în panoul dumneavoastră de administrare ca «plătită», factura se generează singură, iar curierul primește adresa de livrare. Nimeni nu apasă niciun buton. Mecanismul din spate se numește webhook și stă în spatele majorității integrărilor pe care le livrăm: plăți Stripe, e-Factura ANAF, curieri, sincronizare de stoc. Iată ce este, cum funcționează, ce se strică cel mai des și ce plătiți de fapt când cereți o «integrare cu webhook-uri».

Analogia: sunați dumneavoastră sau vă sună ei?

Comandați mâncare la telefon. Varianta 1: sunați restaurantul la fiecare cinci minute și întrebați «e gata?». După a șasea convorbire aflați că da, e gata, dar ați irosit cinci apeluri, iar între ele nu ați știut nimic. Varianta 2: lăsați numărul de telefon, iar restaurantul vă sună în secunda în care comanda iese din bucătărie.

Prima variantă se numește polling: aplicația dumneavoastră întreabă un sistem extern la interval fix, indiferent dacă există ceva nou. A doua variantă e webhook-ul: sistemul extern vă anunță singur, exact în momentul în care se întâmplă evenimentul. Aceeași informație ajunge la dumneavoastră, dar cu un apel în loc de șase și fără pauze de cinci minute în care nu știți nimic.

Definiția strictă: un webhook este un URL din aplicația dumneavoastră la care un alt sistem trimite automat un request HTTP POST de fiecare dată când are loc un eveniment pe care ați ales să îl primiți. Datele sosesc de obicei în format JSON. Atât. Restul articolului e despre consecințele acestei definiții, pentru că ele fac diferența dintre o integrare ieftină care pică în primul weekend și una care funcționează ani.

Cum arată în practică: fluxul unei plăți Stripe

Un flux real, pas cu pas:

1. Clientul își introduce cardul în pagina de plată.
2. Stripe procesează tranzacția. Banii intră în contul dumneavoastră.
3. Stripe trimite automat un POST la adresa pe care ați configurat-o în panoul lor (de exemplu https://api.magazinultau.ro/webhooks/stripe), cu un JSON care descrie evenimentul.
4. Serverul dumneavoastră citește mesajul, marchează comanda #4821 ca plătită, declanșează generarea facturii și confirmă primirea.

Mesajul arată așa (fragment simplificat dintr-un eveniment Stripe real):

{
  "id": "evt_1Q8xL2Kj9z",
  "type": "payment_intent.succeeded",
  "created": 1755235200,
  "data": {
    "object": {
      "id": "pi_3Q8xL2",
      "amount": 24900,
      "currency": "ron",
      "status": "succeeded"
    }
  }
}

Observați "amount": 24900: suma vine în bani-mici, adică 249,00 RON. Detalii de genul acesta fac diferența dintre o integrare corectă și una care vă vinde marfa la o sutime din preț.

Regula de aur a webhook-urilor: serverul dumneavoastră trebuie să confirme primirea repede, în câteva secunde, cu un cod HTTP 200. Procesarea grea (email-uri de confirmare, generare PDF, apel către curier) se face în fundal, după confirmare. Dacă serverul nu răspunde sau răspunde cu eroare, Stripe retrimite evenimentul de mai multe ori, pe parcursul a până la trei zile. Acest comportament de reîncercare e o funcție, nu un defect: vă salvează când serverul e căzut pentru scurt timp. Dar are o consecință importantă: vedeți problema numărul 2 de mai jos.

Webhook vs. API «clasic»: pull sau push

Dacă ați citit articolul despre API REST, știți deja jumătate din poveste. API-ul și webhook-ul folosesc aceeași tehnologie: HTTP și JSON. Diferența e direcția: la API, aplicația dumneavoastră cere date când are nevoie de ele (pull); la webhook, celălalt sistem trimite date în momentul în care ele apar (push). De aceea majoritatea integrărilor folosesc ambele: configurare și verificări prin API, notificări în timp real prin webhook-uri.

Unde întâlniți webhook-uri în afacerea dumneavoastră

• Plăți (Stripe, PayPal, procesatori de card): plată reușită, chargeback, abonament reînnoit, card expirat. Fără webhook-uri, ați activa abonamentele clienților cu ore întârziere sau manual.
• e-Factura (ANAF): ANAF vă anunță când factura trimisă a fost validată sau respinsă. Fără acest mecanism, aflați de o factură respinsă abia la control. Am scris un ghid separat pentru integrarea e-Factura.
• Curieri (FanCourier, Cargus, GLS): statusul AWB-ului se schimbă: ridicat, livrat, returnat. Pe webhook, clientul primește notificare automată, iar dumneavoastră nu mai verificați tracking-ul manual.
• Sincronizare de stoc (eMAG, marketplace-uri, ERP): se vinde un produs în magazin → stocul se actualizează în ERP → webhook-ul propagă schimbarea pe toate canalele, în secunde. Fără el, vindeți produse care nu mai sunt în stoc.

Cele patru probleme clasice: de ce «un mic endpoint» nu e de ajuns

Un webhook funcțional se scrie într-o zi. Un webhook de producție tratează patru probleme pe care le vedeți abia când trec bani prin el:

1. Falsificarea. URL-ul e public: oricine îl cunoaște poate trimite un JSON mincinos de tipul «plata a reușit». De aceea Stripe semnează criptografic fiecare eveniment, iar serverul dumneavoastră trebuie să verifice semnătura înainte să creadă mesajul. Un webhook fără verificarea semnăturii e o ușă descuiată spre banii firmei.
2. Duplicarea. Reîncercările descrise mai sus înseamnă că același eveniment poate sosi de două ori. Dacă abonamentul se activează la fiecare primire, se activează de două ori. Soluția se numește idempotență: se reține ID-ul evenimentului, iar evenimentul se ignoră dacă a mai fost procesat.
3. Ordinea. Evenimentele pot sosi în altă ordine decât cea în care s-au produs: «plata a reușit» poate ajunge înainte de «plata a fost inițiată». Nu construiți logica de business pe ordinea mesajelor.
4. Indisponibilitatea serverului. Deploy, mentenanță, incident: serverul dumneavoastră va fi măcar o dată căzut exact când sosește un webhook important. Furnizorii reîncearcă, dar o implementare serioasă păstrează un jurnal al evenimentelor primite și un proces de reconciliere care compară zilnic ce ați primit cu ce a trimis furnizorul.

Cât costă o implementare corectă

Prețurile de mai jos sunt cele practicate pe piața românească în 2026, consecvente cu estimările din articolul despre API:

Diferența dintre prima linie și a doua nu e «cod în plus», ci diferența dintre o integrare care pică în primul weekend și una care funcționează în producție ani de zile. Prima se scrie într-o zi și se repară la fiecare incident; a doua se scrie în patru zile și nu mai trebuie atinsă.

Patru întrebări care dezvăluie o implementare făcută bine

Chiar dacă nu scrieți cod, puteți testa orice echipă care vă face o integrare cu webhook-uri. Puneți aceste întrebări; răspunsul corect e în paranteze:

1. Verificați semnătura evenimentelor primite? («Da. Fără semnătură validă, mesajul e ignorat.»)
2. Ce se întâmplă dacă același eveniment sosește de două ori? («Îl ignorăm, pentru că reținem ID-ul evenimentului procesat.»)
3. Cât de repede confirmați primirea unui webhook? («Imediat; procesarea efectivă rulează în fundal.»)
4. Cum aflați că ați pierdut un eveniment? («Jurnal + alertă + reconciliere zilnică prin API.»)

Dacă la oricare dintre ele auziți «nu ne-am gândit la asta», ați aflat exact ce aveați nevoie să știți despre calitatea integrării, înainte să o plătiți, nu după primul incident.

Întrebări frecvente

Ce este un webhook?

Un URL din aplicația dumneavoastră la care un sistem extern trimite automat un mesaj HTTP de fiecare dată când se produce un eveniment; de exemplu, Stripe vă anunță când o plată reușește. E mecanismul standard prin care două sisteme schimbă informații fără intervenție umană, în secunde de la producerea evenimentului.

Care e diferența dintre un webhook și un API?

Ambele folosesc HTTP și JSON. La API, aplicația dumneavoastră cere date când are nevoie de ele (pull); la webhook, sistemul extern le trimite automat în momentul în care apar (push). Majoritatea integrărilor reale folosesc ambele mecanisme: configurare și reconciliere prin API, notificări în timp real prin webhook-uri.

Ce se întâmplă dacă serverul nu răspunde la un webhook?

Furnizorul retrimite evenimentul de mai multe ori, pe parcursul a câtorva ore sau chiar zile. Dacă nici după reîncercări mesajul nu ajunge, evenimentul se pierde. De aceea o implementare serioasă include jurnal de evenimente, alerte și o reconciliere zilnică prin API, care compară ce ați primit cu ce a trimis furnizorul.