Event
Rekodi ya change kwenye payment, game session, KYC check, bonus, player profile au object nyingine.
Documentation / Webhooks
Webhooks na event delivery
Weka reliable status na event delivery kati ya systems: kutoka message creation na signature verification hadi receipt acknowledgement, redelivery na error monitoring.
Events
statuses na changes
Signature
authenticity verification
Retries
redelivery
Monitoring
history na diagnostics
Event flow
Kutoka creation hadi acknowledgement
01
Unda event
Weka identifier, type, time, object, status na related data.
02
Sign na send
Tuma event kupitia HTTPS ikiwa na signature na limited timeout.
03
Acknowledge receipt
Baada ya verification, hifadhi event na urudishe successful HTTP response haraka.
04
Retry on error
Retry delivery kwa intervals zinazoongezeka na uhifadhi undelivered events kwa investigation.
Overview
Webhook huripoti state change
Sender anaweza kufanya retry ya delivery, kwa hiyo recipient lazima averify source, aacknowledge receipt na kutumia kila event mara moja tu.
Acknowledgement
Recipient hurudisha successful HTTP response baada ya kuverify na kuhifadhi event kwa kuaminika.
Recovery
Redelivery na reconciliation husaidia kurejesha data baada ya temporary unavailability ya system yoyote kati ya hizo.
Event structure
Event inapaswa kuwa na nini
Consistent message structure hurahisisha verification, routing, duplicate protection na support ya event types tofauti.
Event identifier
Unique value inayotumiwa na system kutambua redelivery na kupata processing history.
Event type
Jina wazi na stable linaloeleza change iliyotokea na jinsi inavyopaswa kuchakatwa.
Creation time
Tarehe na muda event iliundwa, kwa agreed format na time zone.
Related object
Type na identifier ya payment, player, round, request, bonus au object nyingine.
Schema version
Version number husaidia kubadilisha message structure kwa usalama bila kuvuruga active integrations.
Operation correlation
Identifier ya original request, transaction, session au chain ya related actions.
Context
Brand, project, market, environment, provider na data nyingine inayohitajika kwa correct routing.
Event data
Minimum set ya fields zinazohitajika kuchakata change au kufanya subsequent API request.
Signature na verification
Kuverify event authenticity na integrity
Kabla ya kubadilisha data, recipient huverify secure connection, signature, creation time na unique event identifier.
01
Capture raw message
Verify signature dhidi ya raw request body kabla ya kubadilisha JSON format.
02
Kagua timestamp
Kataa request ikiwa event time iko nje ya permitted window.
03
Verify signature
Tumia agreed secret na HMAC au digital-signature algorithm.
04
Kagua identifier
Thibitisha event haijatumika tayari na uhifadhi verification result.
Delivery na retries
HTTP responses na redelivery
Sender lazima atofautishe successful receipt, temporary error na permanent failure, huku recipient akijibu haraka na kwa uwazi.
Successful HTTP response
Huthibitisha event imeverifyiwa na kuhifadhiwa kwa kuaminika kwa further processing.
Limited timeout
Usifanye lengthy processing kabla ya kujibu sender — hifadhi event kwanza.
Redelivery
Retry delivery baada ya temporary network error, unavailability au no response.
Increasing retry interval
Ongeza delay kati ya attempts hatua kwa hatua ili kuepuka additional load.
Undelivered event queue
Baada ya attempts zote kuisha, hifadhi event kwa diagnostics na manual handling.
Manual redelivery
Operator anaweza kutuma selected event tena bila kuunda operation mpya.
Delivery monitoring
Fuatilia idadi ya attempts, responses, latest error na next delivery time.
Alerts
Alert team errors zinapoongezeka, retries zinapoisha au events zinapokusanyika kwenye queue.
Event processing
Duplicate protection na status ordering
Recipient hapaswi kutegemea single delivery au strict event ordering.
Tumia mara moja tu
Hifadhi event identifier kabla ya kubadilisha data.
Acknowledge repeated event bila debit, credit au state change nyingine.
Unganisha event na object pamoja na current state yake.
Hifadhi event na business change kama consistent operation moja.
Ordering na freshness
Linganisha timestamp, sequence number au event version.
Usirudishe object kwenye outdated state wakati older event inafika kwa kuchelewa.
Ruhusu valid transitions tu kati ya statuses.
Ikiwa kuna shaka, omba current object state kupitia API.
Testing
Nini cha kutest kabla ya launch
Test successful delivery, invalid signatures, duplicates, slow responses, out-of-order events na recovery baada ya failure.
Invalid signature
Modified message, unknown key, expired timestamp na unsupported algorithm.
Redelivery
Event ileile hufika mara kadhaa kabla na baada ya processing kukamilika.
Slow response
Recipient huchukua muda mrefu kujibu, connection hukatika au acknowledgement haimfikii sender.
Out-of-order processing
Final status hufika kabla ya intermediate one, na older event huwasilishwa baada ya newer one.
Unavailable endpoint
Test HTTP 5xx errors, DNS, TLS, rate limits na complete exhaustion ya retry attempts.
Delivery history
Attempts, responses, errors na manual redelivery results zote zinapaswa kutafutika kwa event identifier.
Pre-launch checklist
Production delivery huwashwa baada ya security, duplicate protection, redelivery na error monitoring kuthibitishwa.
Test na production environments hutumia endpoints na signing secrets tofauti.
Signature huverifyiwa dhidi ya raw message pamoja na creation time yake.
Event identifier huhifadhiwa na hulinda operations zisitekelezwe zaidi ya mara moja.
Recipient hurudisha successful HTTP response haraka baada ya kuhifadhi event.
Retries, increasing intervals na manual redelivery zimewekwa.
Delivery history na identifier-based search zinapatikana kwa support team.
Unahitaji kuweka reliable event delivery?
Tupatie event list, receiving endpoints na status transition rules. APIACE itasaidia kufafanua message structure, signature verification, redelivery na error monitoring.