Documentation / Webhooks

Webhooks እና event delivery

በsystems መካከል statuses እና eventsን በአስተማማኝ ሁኔታ ያስተላልፉ፦ ከmessage creation እና signature verification እስከ receipt confirmation፣ repeated delivery እና error monitoring።

Security section ክፈት

Events

Statuses እና changes

Signature

Authenticity verification

Retries

Repeated delivery

Control

History እና diagnostics

Event flow

ከcreation እስከ confirmation

RELIABLE DELIVERY

Event ይፍጠሩ

Identifier፣ type፣ time፣ object፣ status እና related data ይግለጹ።

Sign እና send ያድርጉ

Eventውን በHTTPS ከsignature እና limited timeout ጋር ያስተላልፉ።

Receiptን ያረጋግጡ

ከverification በኋላ eventውን ያስቀምጡ እና በፍጥነት successful HTTP response ይመልሱ።

በerror ጊዜ retry ያድርጉ

Deliveryን increasing interval ጋር ይድገሙ እና undelivered eventsን ለanalysis ያስቀምጡ።

በዚህ ገጽ

Event እንደገና ሊደርስ ይችላል

Repeated ወይም delayed delivery መደበኛ operating scenario ነው እና repeated debit ወይም credit ማስከተል የለበትም።

Overview

Webhook ስለ state change ያሳውቃል

Senderው deliveryን ሊደግም ይችላል፣ ስለዚህ receiverው sourceን ማረጋገጥ፣ receiptን ማረጋገጥ እና እያንዳንዱን event አንድ ጊዜ ብቻ መተግበር አለበት።

Event

Payment፣ game session፣ KYC check፣ bonus፣ player profile ወይም ሌላ object ላይ ስለተፈጠረ change መዝገብ።

Acknowledgement

Receiverው eventውን ካረጋገጠ እና በአስተማማኝ ሁኔታ ካስቀመጠ በኋላ successful HTTP response ይመልሳል።

Recovery

Repeated sending እና reconciliation አንዱ system ለጊዜው ሳይገኝ ከቆየ በኋላ dataን ለመመለስ ይረዳሉ።

የevent ይዘት

Eventው ምን data ማካተት አለበት

የተዋሃደ message structure verification፣ routing፣ duplicate protection እና የተለያዩ event types ድጋፍን ያቀላጥፋል።

Event ID

Systemው repeated deliveryን የሚለይበት እና processing historyን የሚያገኝበት unique value።

Event type

የተፈጠረውን change እና የprocessing methodን የሚወስን ግልጽ እና stable name።

Creation time

Eventው በተስማማ format እና time zone የተፈጠረበት date እና time።

Related object

የpayment፣ player፣ round፣ application፣ bonus ወይም ሌላ object type እና ID።

Schema version

Version number አሁን ያሉ connectionsን ሳያበላሽ message structureን በደህንነት ለመቀየር ይረዳል።

Operation correlation

የoriginal request፣ transaction፣ session ወይም related-action chain identifier።

Context

Brand፣ project፣ market፣ environment፣ provider እና ለcorrect routing የሚያስፈልጉ ሌሎች data።

Event data

Changeን ለማስኬድ ወይም በኋላ API request ለማድረግ የሚያስፈልጉ minimum fields።

Signature እና verification

Event authenticity እና integrity verification

Dataን ከመቀየሩ በፊት receiverው secure connection፣ signature፣ creation time እና unique event ID ያረጋግጣል።

Authentication እና security

Original message ያግኙ

JSON formatን ከመቀየሩ በፊት signatureን በoriginal request body ላይ ያረጋግጡ።

Timeን ያረጋግጡ

Event time ከተፈቀደው interval ውጭ ከሆነ requestውን ውድቅ ያድርጉ።

Signatureን ያረጋግጡ

የተስማማ secret እና HMAC ወይም digital-signature algorithm ይጠቀሙ።

Identifierን ያረጋግጡ

Eventው ከዚህ በፊት እንዳልተተገበረ ያረጋግጡ እና verification resultን ያስቀምጡ።

Delivery እና retries

HTTP responses እና repeated delivery

Senderው successful receipt፣ temporary error እና permanent rejectionን መለየት አለበት፣ receiverው ደግሞ በፍጥነት እና ግልጽ መልስ መስጠት አለበት።

Successful HTTP response

Eventው ተረጋግጦ ለቀጣይ processing በአስተማማኝ ሁኔታ እንደተቀመጠ ያረጋግጣል።

Limited wait time

Senderን ከመመለስ በፊት long processing አያድርጉ — መጀመሪያ eventውን ያስቀምጡ።

Repeated sending

Temporary network error፣ unavailability ወይም no response ሲኖር deliveryን ይድገሙ።

Increasing interval

ተጨማሪ load እንዳይፈጠር በattempts መካከል ያለውን pause ቀስ በቀስ ያሳድጉ።

Undelivered-event queue

Attempts ከተሟጠጡ በኋላ eventውን ለdiagnostics እና manual processing ያስቀምጡ።

Manual resend

Operatorው አዲስ operation ሳይፈጥር የተመረጠውን event እንደገና ሊልክ ይችላል።

Delivery monitoring

Attempt count፣ responses፣ last error እና next-send time ይከታተሉ።

Notifications

Errors ሲጨምሩ፣ attempts ሲያልቁ እና events በqueue ውስጥ ሲከማቹ teamውን ያሳውቁ።

Event processing

Duplicate protection እና status ordering

Receiverው በsingle delivery ወይም strict event order ላይ መመርኮዝ የለበትም።

Apply once

Dataን ከመቀየሩ በፊት event IDን ያስቀምጡ።

Repeated eventን ያለrepeated debit፣ credit ወይም change ያረጋግጡ።

Eventውን ከobject እና current state ጋር ያገናኙ።

Eventውን እና business changeን እንደ አንድ consistent operation ያስቀምጡ።

Order እና freshness

Time፣ sequence number ወይም event version ያነፃፅሩ።

Delayed delivery ሲኖር objectውን ወደ stale state አይመልሱ።

በstatuses መካከል የተፈቀዱ transitions ብቻ ይፍቀዱ።

ጥርጣሬ ሲኖር current object stateን በAPI ይጠይቁ።

Testing

ከlaunch በፊት ምን መፈተሽ አለበት

Successful delivery፣ invalid signature፣ retries፣ slow response፣ event-order changes እና recovery after failure ይፈትሹ።

Invalid signature

Modified message፣ unknown key፣ expired time እና unsupported algorithm።

Repeated delivery

ተመሳሳይ event processing ከመጠናቀቁ በፊት እና በኋላ ብዙ ጊዜ ይደርሳል።

Slow response

Receiverው በጣም ዘግይቶ ይመልሳል፣ connection ይቋረጣል ወይም acknowledgement ወደ sender አይደርስም።

Out-of-order processing

Final status ከintermediate status በፊት ይደርሳል፣ አሮጌ event ደግሞ ከአዲሱ በኋላ ይደርሳል።

Unavailable endpoint

HTTP 5xx፣ DNS፣ TLS፣ rate limits እና attempts ሙሉ በሙሉ መሟጠጥ ይፈትሹ።

Delivery history

በevent ID ሁሉም attempts፣ responses፣ errors እና manual-send result ሊገኙ ይገባል።

ከlaunch በፊት checklist

Production delivery security፣ duplicate protection፣ repeated sending እና error monitoring ከተፈተሹ በኋላ ይነቃል።

Test እና production environments የተለያዩ endpoints እና signing secrets ይጠቀማሉ።

Signature በoriginal message ላይ creation timeን ከግምት በማስገባት ይረጋገጣል።

Event ID ይቀመጣል እና operationsን ከrepeated execution ይጠብቃል።

Eventውን ካስቀመጠ በኋላ receiverው በፍጥነት successful HTTP response ይመልሳል።

Retries፣ increasing interval እና manual resend ተዘጋጅተዋል።

Delivery history እና identifier search ለsupport team ይገኛሉ።

Testing section ክፈት

Reliable event delivery ማዘጋጀት ይፈልጋሉ?

የevents ዝርዝር፣ receiving endpoints እና status-change rules ይላኩ። APIACE message structure፣ signature verification፣ repeated delivery እና error control ለመወሰን ይረዳል።

APIACEን ያነጋግሩ Integration process ክፈት