Ce este un webhook — explicat pentru non-tehnici

Clientul plătește cu cardul. Peste câteva secunde, comanda lui apare în panoul tău de admin 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 e responsabil pentru majoritatea integrărilor pe care le vindem efectiv: 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ătești de fapt când ceri o «integrare cu webhook-uri».

Analogia: suni tu sau te sună ei?

Comanzi mâncare la telefon. Varianta 1: suni restaurantul la fiecare cinci minute și întrebi «e gata?». După a șasea convorbire afli că da, e gata — dar ai irosit cinci apeluri, iar între ele nu ai știut nimic. Varianta 2: lași numărul tău, iar restaurantul te sună în secunda în care comanda iese din bucătărie.

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

Definiția strictă: un webhook este un URL din aplicația ta la care un alt sistem trimite automat un request HTTP POST de fiecare dată când are loc un eveniment pe care ai stabilit să îl primești. Datele sosesc de obicei în format JSON. Atât. Restul articolului e despre consecințele acestei definiții — pentru că ele sunt 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 tău.
3. Stripe trimite automat un POST la adresa pe care ai configurat-o în panoul lor — de exemplu https://api.magazinultau.ro/webhooks/stripe — cu un JSON care descrie evenimentul.
4. Serverul tău 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"
    }
  }
}

Observă "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 îți vinde marfa la o sutime din preț.

Regula de aur a webhook-urilor: serverul tău 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ă nu răspunzi sau răspunzi 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: te salvează când serverul tău e căzut pentru scurt timp. Dar are o consecință importantă — vezi problema numărul 2 de mai jos.

Webhook vs. API «clasic» — pull sau push

Dacă ai citit articolul despre API REST, știi 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 ta 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âlnești webhook-uri în afacerea ta

• Plăți (Stripe, PayPal, procesatori de card) — plată reușită, chargeback, abonament reînnoit, card expirat. Fără webhook-uri, ai activa abonamentele clienților cu ore întârziere sau manual.
• e-Factura (ANAF) — ANAF te anunță când factura trimisă a fost validată sau respinsă. Fără acest mecanism, afli 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 tu nu mai verifica 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, vinzi produse dispărute din 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 vezi abia când trec bani prin el:

1. Falsificarea. URL-ul tău 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 tău trebuie să verifice semnătura înainte să creadă mesajul. Un webhook fără verificarea semnăturii e o ușă descuiată în casa ta financiară.
2. Duplicarea. Reîncercările descrise mai sus înseamnă că același eveniment poate sosi de două ori. Dacă activezi abonamentul la fiecare primire, îl activezi de două ori. Soluția se numește idempotență: reții ID-ul evenimentului și îl ignori dacă l-ai mai procesat.
3. Ordinea. Evenimentele pot sosi în altă ordine decât cea în care s-au produs — «plata a reușit» poate ajunge la tine înainte de «plata a fost inițiată». Nu construi logica de business pe ordinea mesajelor.
4. Indisponibilitatea serverului. Deploy, mentenanță, incident — serverul tău 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 ai primit cu ce a trimis furnizorul.

Cât costă o implementare corectă

Prețurile de mai jos sunt cele pe care le practici 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» — e diferența dintre o integrare care pică în primul weekend și una care funcționează în producție ani de zile. Prima o scrii într-o zi și o repari la fiecare incident; a doua o scrii în patru zile și nu o mai atingi.

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

Chiar dacă nu scrii cod, poți testa orice echipă care îți face o integrare cu webhook-uri. Pune 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 — 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 «nu ne-am gândit la asta», ai aflat exact ce ai nevoie să știi despre calitatea integrării — înainte să o plătești, nu după primul incident.

Citește în continuare

• Ce este un API REST — explicat fără jargon
• Ghid: Integrare API ANAF e-Factura 2026
• Servicii: Integrări API