Webhook-uri

Un webhook este modalitatea prin care e-bon împinge evenimente către sistemele tale în momentul în care se produc — un bon este emis, o comandă se finalizează, un dispozitiv trece offline, un raport Z este generat. Îi dai e-bon un URL HTTPS, alegi evenimentele care te interesează și, de atunci înainte, fiecare eveniment relevant este livrat la endpoint-ul tău ca un POST JSON semnat. Fără polling, fără apeluri API din partea ta, fără așteptare. Referința completă pentru fiecare tip de eveniment, cele patru anteturi HTTP X-EBon-* și fluxul de verificare a semnăturii HMAC SHA-256 se află pe pagina Evenimente webhook din referința API — această pagină din Portal este despre cum să configurezi un endpoint fără a scrie cod.

Găsește webhook-urile tale

Deschide meniul lateral al Portalului și alege Setări → Webhook-uri. Pagina se află la /portal/settings/webhooks și listează fiecare endpoint webhook înregistrat pentru organizația ta, împreună cu URL-ul, evenimentele la care este abonat, starea activă/inactivă, momentul ultimei livrări și numărul de eșecuri consecutive.

Creează un endpoint

Copiază secretul (afișat o singură dată)

În momentul în care un endpoint este creat — și din nou de fiecare dată când regenerezi secretul — e-bon îți arată secretul de semnare într-un modal dedicat:

Folosește butonul de copiere de lângă secret pentru a-l pune în clipboard, apoi inserează-l în managerul tău de secrete (1Password, Vault, providerul tău de CI etc.) înainte de a apăsa Gata. Secretul este ceea ce serviciul tău receptor folosește pentru a calcula semnătura HMAC SHA-256 din antetul X-EBon-Signature al fiecărei livrări primite. Snippeturile complete de verificare — atât Node.js, cât și formula openssl — se află în referința API: vezi Verifică semnătura webhook-ului.

Gestionează endpoint-urile existente

Vizualizarea de listă de pe /portal/settings/webhooks afișează un card per endpoint. Fiecare card scoate la suprafață:

• URL-ul complet (cu font monospace, copiabil).
• O insignă Activ / Inactiv alimentată de flag-ul enabled.
• Evenimentele abonate ca insigne mici colorate primar.
• Momentul ultimei livrări (relativ — „acum 2 minute”, „acum 3 ore”).
• O bandă roșie cu numărul de eșecuri atunci când endpoint-ul are eșecuri consecutive („3 eșecuri”, „12 eșecuri”) — același failureCount pe care API-ul îl expune pe înregistrarea webhook-ului.

Trei butoane se află în partea dreaptă a fiecărui rând:

• Trimite test (iconiță avion de hârtie) — vezi Trimite o livrare de test.
• Editează (iconiță creion) — deschide modalul de editare.
• Șterge (iconiță coș de gunoi roșie) — deschide modalul de confirmare a ștergerii.

Editează un endpoint

Modalul Editează webhook îți permite să schimbi URL-ul, descrierea, evenimentele abonate și comutatorul Activat. URL-ul este validat după aceeași regulă https:// ca la creare; lista de evenimente cere în continuare cel puțin o intrare. Apasă Salvează pentru a persista modificările — nu se generează niciun secret nou, deci receptorii existenți continuă să funcționeze.

Același modal are și un buton Regenerează secretul (vezi mai jos) și un tabel Livrări recente la bază — o vizualizare paginată și filtrabilă (status: Toate / În așteptare / Succes / Eșuat) a celor mai recente încercări de livrare pentru acest endpoint, care arată tipul evenimentului, statusul, codul de răspuns HTTP, numărul încercării și momentul. Folosește-l pentru a depana un receptor cu probleme: un rând cu status „Eșuat” și HTTP 500 îți spune că endpoint-ul este accesibil, dar aruncă erori; un rând cu status „Eșuat” și HTTP — înseamnă de obicei că cererea nu s-a conectat niciodată (DNS / TLS / timeout).

Regenerează secretul de semnare

Apasă Regenerează secretul în modalul de editare pentru a invalida secretul curent și a genera unul nou. Modalul de afișare se deschide imediat cu noul secret — copiază-l, apoi actualizează fiecare receptor care verifică semnături.

Șterge un endpoint

Apasă iconița roșie de coș de gunoi de pe orice rând pentru a deschide modalul Șterge webhook. Modalul te întreabă: „Sigur doriți să ștergeți webhook-ul <URL>? Această acțiune nu poate fi anulată.” Apasă Șterge pentru a confirma.

Ștergerea este imediată: endpoint-ul este eliminat și nu se mai trimite niciun eveniment către el. Nu există anulare. Pentru a pune în pauză un endpoint fără a renunța la configurație, oprește comutatorul Activat din modalul de editare în loc.

Trimite o livrare de test

Butonul cu avion de hârtie de pe fiecare rând declanșează o livrare de test sincronă către acel endpoint cu evenimentul canonic webhook.test. Corpul cererii este exact:

{
  "test": true,
  "message": "This is a test event from e-bon."
}

…încadrat în plicul standard (vezi Inspectează plicul evenimentului) și semnat cu secretul curent al endpoint-ului. Portalul așteaptă răspunsul receptorului și afișează una dintre cele două notificări:

• Webhook-ul de test a fost livrat cu succes. — receptorul a returnat 2xx în limita timeout-ului de 10 secunde.
• Webhook-ul de test a eșuat: <eroare> — orice altceva (răspuns non-2xx, timeout, eroare de conexiune, eroare TLS). Mesajul de eroare este ceea ce a raportat dispatcher-ul.

Testul nu cere ca vreunul dintre evenimentele abonate să fie webhook.test — testul este permis întotdeauna, indiferent de lista de abonamente. Folosește-l oricând vrei să confirmi că URL-ul este accesibil, lanțul TLS este valid și verificarea semnăturii ta acceptă secretul curent.

Gestionează dezactivarea automată la eșecuri persistente

e-bon reîncearcă livrările eșuate automat, cu backoff exponențial. Dacă un endpoint acumulează 20 de eșecuri consecutive, abonamentul este setat automat pe enabled: false și nu mai primește livrări noi — îl vei vedea trecând la insigna roșie Inactiv în listă. Reactivează-l din modalul de editare după ce receptorul este reparat.

Programul exact de backoff (5 încercări, ~10s timeout per încercare) și regula de dezactivare automată se află în referința API: vezi Gestionează reîncercările.

Unde mergi mai departe

• Evenimente webhook — referința payload-ului per eveniment, cele patru anteturi HTTP X-EBon-*, fluxul de verificare a semnăturii HMAC SHA-256 (Node.js + openssl) și programul complet de livrare + reîncercare.
• API webhook-uri — CRUD programatic pentru abonamentele webhook folosind o cheie API (POST /api/v1/org/webhooks, PATCH /…/{id}, DELETE /…/{id}, POST /…/{id}/test, POST /…/{id}/rotate-secret).
• Chei API — credențialul pentru citire. Cheile API trag date; webhook-urile împing evenimente. Majoritatea integrărilor le folosesc pe ambele.
• Facturare — gestionează abonamentul și facturile organizației tale.