Ce este un webhook? Cum își trimit aplicațiile notificări

Un webhook este un mesaj automat pe care un serviciu îl trimite aplicației tale în momentul în care se întâmplă ceva. Când plata unui client reușește, Stripe trimite un webhook la o adresă din aplicația ta, spunând „plată reușită, iată detaliile”, iar aplicația reacționează — marchează comanda ca plătită, trimite chitanța, deblochează contul. Pe scurt: un API este aplicația ta care pune o întrebare altui serviciu; un webhook este alt serviciu care îți sună aplicația ca să-ți spună ceva.

De ce contează când construiești cu AI

De îndată ce aplicația ta primește plăți, primește trimiteri de formulare din alt instrument sau se conectează la servicii precum GitHub, Shopify sau un calendar, vei întâlni webhook-uri. De obicei, acesta este modul corect de a afla că ceva s-a întâmplat — dar tocmai aici aplicațiile construite cu AI greșesc adesea subtil:

• Endpoint-ul acceptă orice cerere, deci oricine poate falsifica un eveniment „plată reușită”.
• Aplicația acordă acces pe pagina de redirecționare a checkout-ului, în loc de webhook, deci cei care închid fereastra devreme nu primesc ce au plătit, iar cei care găsesc URL-ul de succes îl primesc gratis.
• Același eveniment ajunge de două ori, iar clientul primește două comenzi sau două emailuri.

Să știi cum funcționează webhook-urile îți permite să ceri protecțiile de la început.

O analogie din viața de zi cu zi: un SMS de livrare

Poți afla dacă coletul tău a sosit în două moduri. Poți merge la ușa din față la fiecare zece minute ca să verifici (asta e polling — aplicația ta cere în mod repetat unui API „e ceva nou?”). Sau curierul îți trimite un SMS când a livrat (asta e un webhook).

SMS-ul este clar mai bun — atât timp cât poți avea încredere în el. Dacă oricine ar putea să-ți trimită un mesaj „colet livrat”, ai vrea o cale de a ști că a venit cu adevărat de la curier. Și dacă telefonul tău era închis când a venit mesajul, ai vrea ca un curier să încerce din nou mai târziu. Aceste două aspecte — verificarea și reîncercările — reprezintă cea mai mare parte a ceea ce face webhook-urile dificile.

Cum funcționează un webhook, pas cu pas

1. Creezi un endpoint în backend-ul aplicației: o adresă de tipul https://yourapp.com/webhooks/stripe care acceptă cereri POST.
2. Înregistrezi adresa la furnizor și alegi ce evenimente vrei (de exemplu, „checkout finalizat” și „abonament anulat”).
3. Furnizorul îți oferă un secret de semnare. Îl păstrezi ca secret pe serverul tău — vezi variabilele de mediu și secretele.
4. Are loc un eveniment. Furnizorul trimite o cerere HTTP la adresa ta, cu un corp JSON care descrie evenimentul și un antet cu semnătura.
5. Aplicația ta verifică semnătura, înregistrează ID-ul evenimentului, răspunde rapid cu un cod de succes (200) și abia apoi face munca.
6. Dacă aplicația nu răspunde cu succes, mulți furnizori încearcă din nou mai târziu.

Semnături

O semnătură dovedește că cererea vine de la furnizor și că nu a fost modificată. Stripe, de exemplu, calculează un HMAC (o amprentă cu cheie) cu SHA-256 peste corpul cererii și un timestamp, folosind secretul de semnare, și o trimite în antetul Stripe-Signature. Aplicația ta face același calcul cu propria copie a secretului; dacă rezultatele coincid, cererea este autentică. Pentru că timestamp-ul este și el semnat, poți respinge cererile vechi pe care cineva le-a înregistrat și le redă mai târziu — bibliotecile Stripe au implicit o toleranță de cinci minute, conform documentației sale din septembrie 2026.

Un detaliu practic: semnătura se calculează pe corpul brut al cererii. Dacă framework-ul tău parsează și reformatează JSON-ul înainte de verificare, verificarea eșuează. Este o eroare foarte frecventă.

Reîncercări, duplicate și ordine

Furnizorii diferă, deci verifică documentația fiecăruia. Începând cu septembrie 2026:

Documentația Stripe mai spune că evenimentele nu sunt garantate să sosească în ordinea în care s-au petrecut și că același eveniment poate sosi, uneori, de mai multe ori, așa că recomandă urmărirea ID-urilor evenimentelor.

Lecția generală rămâne valabilă pentru orice furnizor: evenimentele pot sosi întârziate, de mai multe ori și în altă ordine. Handler-ul tău ar trebui să fie idempotent — procesarea aceluiași eveniment de două ori produce același efect ca procesarea o singură dată.

Un exemplu practic: deblocarea unui curs plătit

Vinzi un curs online. Un student apasă Cumpără, plătește pe pagina de checkout găzduită de Stripe și este trimis înapoi pe site-ul tău.

Varianta fragilă: pagina de „mulțumim” deblochează cursul. Dacă studentul închide browserul în timpul redirecționării, a plătit, dar nu are acces. Dacă cineva ghicește URL-ul paginii de mulțumire, primește acces fără să plătească.

Varianta cu webhook:

1. Când Stripe confirmă plata, trimite un eveniment checkout.session.completed la /webhooks/stripe.
2. Backend-ul tău verifică semnătura cu secretul de semnare. Dacă eșuează, răspunde 400 și nu face nimic.
3. Verifică dacă acel ID de eveniment a fost deja procesat. Dacă da, răspunde 200 și se oprește.
4. Salvează ID-ul evenimentului, răspunde 200 și apoi acordă studentului accesul și trimite un email de bun venit.
5. Pagina de „mulțumim” doar spune „Plată primită — cursul tău va apărea în câteva momente” și verifică starea accesului studentului.

Mai târziu, dacă un abonament este anulat sau o cartea eșuează, alte evenimente webhook îi spun aplicației să elimine sau să suspende accesul. Așa rămân produsele pe abonament sincronizate cu facturarea — vezi ce este SaaS și cum adaugi plăți în aplicația ta.

Termeni-cheie

• Endpoint: adresa din aplicația ta care primește webhook-urile.
• Eveniment / payload: ce s-a întâmplat și datele care îl descriu (de obicei JSON).
• Secret de semnare: secretul comun folosit pentru verificarea semnăturilor.
• Idempotent: sigur de rulat de mai multe ori, cu același rezultat.
• Polling: a cere în mod repetat unui API modificări, în loc să aștepți un webhook.
• Tunel: un instrument care dă unui laptop o adresă publică temporară, ca webhook-urile să ajungă la el în timpul dezvoltării.

Greșeli frecvente și idei greșite

• Neverificarea semnăturilor. Adresa endpoint-ului nu este secretă. Verificarea este cea care face cererea de încredere.
• Munca lentă înainte de răspuns. Trimiterea de emailuri sau generarea de PDF-uri înainte de a răspunde poate duce la timeout-uri, care declanșează reîncercări, care produc duplicate.
• Presupunerea „exact o dată, în ordine”. Înregistrează ID-urile evenimentelor și nu te baza pe ordinea de sosire.
• Folosirea unui URL de previzualizare. Webhook-urile au nevoie de o adresă publică și stabilă. Previzualizările private și localhost nu sunt accesibile din internet; folosește URL-ul publicat (sau un tunel în timpul testării).
• Amestecarea secretelor de test cu cele live. Furnizorii emit adesea secrete de semnare diferite pentru modul test și cel live. Păstrează-le pe amândouă și folosește-l pe cel corect.
• Încrederea oarbă în payload pentru decizii importante. Pentru acțiuni cu miză mare, este rezonabil să preiei starea cea mai recentă din API-ul furnizorului, după ce primești evenimentul.

Ce să ceri constructorului tău AI

Adaugă un endpoint POST /webhooks/stripe pe server. Verifică semnătura Stripe folosind corpul brut al cererii și secretul STRIPE_WEBHOOK_SECRET. Respinge semnăturile invalide cu 400. Salvează fiecare ID de eveniment și sari peste evenimentele deja procesate. Răspunde rapid cu 200, apoi tratează checkout.session.completed marcând comanda ca plătită și trimițând chitanța. Înregistrează tipul evenimentului. Nu acorda acces de pe pagina de succes a checkout-ului.

Apoi testează: trimite un eveniment de test din panoul furnizorului, trimite același eveniment din nou și trimite o cerere cu o semnătură greșită. Doar primul ar trebui să schimbe ceva.

Webhook-uri în Mythex

Mythex nu rulează un serviciu separat de webhook-uri; îi ceri agentului să adauge un endpoint de webhook în propriul backend al aplicației și îi indici furnizorului URL-ul tău publicat, deoarece webhook-urile au nevoie de o adresă publică. Secretul de semnare intră în secretele proiectului tău, iar dacă îl schimbi pe o aplicație live, publici din nou. Rețeta din documentație handling webhooks are un prompt de pornire, iar șabloanele de magazin sunt un bun punct de plecare pentru aplicațiile care acceptă plăți.

Întrebări