Eveniment
Înregistrarea unei modificări a unei plăți, sesiuni de joc, verificări KYC, unui bonus, profil de jucător sau altui obiect.
Documentație / Webhook-uri
Webhook-uri și livrarea evenimentelor
Configurați transmiterea fiabilă a stărilor și evenimentelor între sisteme: de la crearea mesajului și verificarea semnăturii până la confirmarea primirii, relivrare și monitorizarea erorilor.
Evenimente
stări și modificări
Semnătură
verificarea autenticității
Repetări
relivrare
Control
istoric și diagnosticare
Traseul evenimentului
De la creare la confirmare
01
Creați evenimentul
Indicați identificatorul, tipul, ora, obiectul, starea și datele asociate.
02
Semnați și trimiteți
Transmiteți evenimentul prin HTTPS, cu semnătură și un timp limitat de așteptare.
03
Confirmați primirea
După verificare, salvați evenimentul și returnați rapid un răspuns HTTP reușit.
04
Repetați la eroare
Repetați livrarea cu intervale tot mai mari și păstrați evenimentele nelivrate pentru analiză.
Prezentare generală
Webhook-ul anunță o modificare de stare
Expeditorul poate repeta livrarea, de aceea destinatarul trebuie să verifice sursa, să confirme primirea și să aplice fiecare eveniment o singură dată.
Confirmare
Destinatarul returnează un răspuns HTTP reușit după verificarea și stocarea fiabilă a evenimentului.
Recuperare
Relivrarea și reconcilierea ajută la refacerea datelor după indisponibilitatea temporară a unuia dintre sisteme.
Structura evenimentului
Ce date trebuie să conțină un eveniment
O structură consecventă a mesajului simplifică verificarea, rutarea, protecția împotriva repetărilor și suportul pentru diferite tipuri de evenimente.
Identificatorul evenimentului
O valoare unică prin care sistemul recunoaște relivrarea și găsește istoricul procesării.
Tipul evenimentului
O denumire clară și stabilă care definește modificarea produsă și modul de procesare.
Ora creării
Data și ora creării evenimentului, în formatul și fusul orar convenite.
Obiect asociat
Tipul și identificatorul plății, jucătorului, rundei, solicitării, bonusului sau altui obiect.
Versiunea structurii
Numărul versiunii ajută la modificarea sigură a structurii mesajului fără a afecta integrările active.
Corelare cu operațiunea
Identificatorul solicitării inițiale, tranzacției, sesiunii sau lanțului de acțiuni asociate.
Context
Brand, proiect, piață, mediu, furnizor și alte date necesare pentru rutarea corectă.
Datele evenimentului
Setul minim de câmpuri necesare pentru procesarea modificării sau efectuarea unei solicitări API ulterioare.
Semnătură și verificare
Verificarea autenticității și integrității evenimentului
Înainte de modificarea datelor, destinatarul verifică conexiunea securizată, semnătura, ora creării și identificatorul unic al evenimentului.
01
Preluați mesajul brut
Verificați semnătura pe corpul brut al solicitării înainte de a modifica formatul JSON.
02
Verificați ora
Respingeți solicitarea dacă ora evenimentului se află în afara intervalului permis.
03
Verificați semnătura
Utilizați secretul și algoritmul HMAC sau de semnătură digitală convenite.
04
Verificați identificatorul
Asigurați-vă că evenimentul nu a fost deja aplicat și salvați rezultatul verificării.
Livrare și repetări
Răspunsuri HTTP și relivrare
Expeditorul trebuie să distingă primirea reușită, eroarea temporară și refuzul permanent, iar destinatarul să răspundă rapid și fără ambiguități.
Răspuns HTTP reușit
Confirmă că evenimentul a fost verificat și stocat fiabil pentru procesare ulterioară.
Timp de așteptare limitat
Nu efectuați o procesare îndelungată înainte de a răspunde expeditorului — salvați mai întâi evenimentul.
Relivrare
Repetați livrarea în cazul unei erori temporare de rețea, indisponibilității sau lipsei răspunsului.
Creșterea intervalului
Măriți treptat pauza dintre încercări pentru a nu crea încărcare suplimentară.
Coada evenimentelor nelivrate
După epuizarea încercărilor, păstrați evenimentul pentru diagnosticare și procesare manuală.
Relivrare manuală
Operatorul poate retrimite evenimentul selectat fără a crea o operațiune nouă.
Monitorizarea livrării
Urmăriți numărul de încercări, răspunsurile, ultima eroare și ora următoarei livrări.
Notificări
Notificați echipa când crește numărul erorilor, se epuizează încercările sau se acumulează evenimente în coadă.
Procesarea evenimentelor
Protecție împotriva repetărilor și ordinea stărilor
Destinatarul nu trebuie să se bazeze pe o singură livrare sau pe o ordine strictă a evenimentelor.
Aplicare o singură dată
Salvați identificatorul evenimentului înainte de modificarea datelor.
Confirmați un eveniment repetat fără o nouă debitare, creditare sau modificare de stare.
Legați evenimentul de obiect și de starea lui curentă.
Salvați evenimentul și modificarea de afaceri ca o singură operațiune coerentă.
Ordine și actualitate
Comparați ora, numărul de secvență sau versiunea evenimentului.
Nu readuceți un obiect la o stare învechită atunci când un eveniment mai vechi este livrat cu întârziere.
Permiteți numai tranziții valide între stări.
În caz de îndoială, solicitați starea actuală a obiectului prin API.
Testare
Ce trebuie verificat înainte de lansare
Verificați livrarea reușită, semnătura invalidă, duplicatele, răspunsul lent, schimbarea ordinii evenimentelor și recuperarea după o defecțiune.
Semnătură invalidă
Mesaj modificat, cheie necunoscută, marcaj temporal expirat și algoritm neacceptat.
Relivrare
Același eveniment sosește de mai multe ori înainte și după finalizarea procesării.
Răspuns lent
Destinatarul răspunde prea lent, conexiunea se întrerupe sau confirmarea nu ajunge la expeditor.
Procesare în ordine greșită
Starea finală sosește înaintea celei intermediare, iar un eveniment mai vechi este livrat după unul mai nou.
Endpoint indisponibil
Testați erorile HTTP 5xx, DNS, TLS, limitările de frecvență și epuizarea completă a încercărilor de repetare.
Istoricul livrării
Toate încercările, răspunsurile, erorile și rezultatele relivrării manuale trebuie să poată fi găsite după identificatorul evenimentului.
Listă de verificare înainte de lansare
Livrarea în producție este activată după verificarea securității, protecției împotriva duplicatelor, relivrării și monitorizării erorilor.
Mediile de testare și producție folosesc endpointuri și secrete de semnare diferite.
Semnătura este verificată pe baza mesajului brut, împreună cu momentul creării acestuia.
Identificatorul evenimentului este salvat și protejează operațiunile împotriva executării repetate.
Destinatarul returnează rapid un răspuns HTTP de succes după salvarea evenimentului.
Sunt configurate încercările repetate, creșterea intervalelor și relivrarea manuală.
Istoricul livrării și căutarea după identificator sunt disponibile echipei de suport.
Trebuie configurată o livrare fiabilă a evenimentelor?
Transmiteți lista evenimentelor, endpointurile de recepție și regulile de schimbare a stărilor. APIACE va ajuta la definirea structurii mesajelor, verificării semnăturii, relivrării și monitorizării erorilor.