REST, gRPC we iGaming WebHook: nagyşlar we anti-nagyşlar

Makalanyň doly teksti

💡 18+. iGaming önüm we in engineeringenerçilik toparlary üçin tehniki material. Oýnamaga çagyryş ýok. "Platforma" diýmek PAM/gapjyk/kassa/bonuslar/RG. "Üpjün ediji" - RGS/live/jekpotlar/agregatorlar.

1) Teswirnamalaryň kartasy: kim näme üçin jogapkär?

REST - HTTP/JSON boýunça ähliumumy sinhron soraglar. Aç-açan keş, ýönekeý düzediş, B2B integrasiýalary we administratiw-API üçin amatly.

gRPC - HTTP/2 üstünde ýokary öndürijilikli ikilik RPC: pes gizlinlik, akym, berk shemalar. Gyzgyn pul ýollary (wallet/settle), içerki hyzmatlar we uzak möhletli akymlar (live) üçin amatly.

Webhuklar - alyjydan iberijä gaýdyp gelmek (callback). ("Pul düşdi", "çäk işledi"), inisiatiwaçy hemişe netijä garaşýan adam däl.

Altyn düzgün:

Pul gaty üýtgewsizligi we deňagramlylygy bolan sinhron RPC (REST/gRPC) boýunça gidýär. Telemetriýa we işewürlik wakalary - asinhron (webhuklar + wakalaryň tekeri).

2) Nusgawy ýollar we maslahat berlen kanallar

Ýol	Maslahat berildi	Näme üçin
`bets. authorize` (hold)	gRPC (içinde )/REST (B2B)	iň az gizlinlik, berk SLA
`bets. settle` → `wallet. credit`	gRPC sinhron + teker hadysasy	pul = ACID; wakalar = syn ediliş
`cashier. deposit/withdraw`	REST + idempotentlik	PSP bilen integrasiýa, söwda
`RG check / stop`	gRPC/REST synply	durma signallary derrew işlemeli
`bonus. issue/consume`	REST synply	iş logikasy, orta SLA
`jackpot. trigger/payout`	gRPC/REST + waka	pul şertnamasy + audit
Telemetriýa, analitika, aladalar	Webhuki + teker (Kafka/Pulsar)	durnuklylygy we gerimi
Live status/kataloglar	gRPC streaming / Server-Sent Events	anketalary we laglary azaltmak

3) Şertnama gönükdirilen dizaýn

3. 1 REST (bölekler)


POST /v1/bets/authorize
Headers: X-Idempotency-Key: bet_r_8c12_1, X-Trace-Id: tr_a1b2
{
"session_id":"s_456",  "bet_id":"b_001",  "round_id":"r_8c12",  "amount":{"amount":2. 00,"currency":"EUR"}
}
→ 200 {"status":"authorized","hold_id":"h_zz1"}

Hatalar (ýekeje shema):


409
{"code":"DUPLICATE","message":"Bet already authorized","retryable":false,"trace_id":"tr_a1b2"}

3. 2 gRPC (protobuf, ýönekeýleşdirilen)

proto syntax = "proto3";
package wallet. v1;

message Money { int64 minor_units = 1; string currency = 2; } // cents message AuthorizeBetReq { string session_id=1; string bet_id=2; string round_id=3; Money amount=4; string idempotency_key=5; }
message AuthorizeBetRes { string status=1; string hold_id=2; }

service Wallet {
rpc AuthorizeBet(AuthorizeBetReq) returns (AuthorizeBetRes);
rpc SettleBet(SettleReq) returns (SettleRes);
}

3. 3 Webhuklar (abunalyk mysaly)


POST https://provider. example/webhooks
{
"topic":"wallet. credit. ok",  "callback_url":"https://rgs. example/journal",  "secret":"", "version":"1. 2"
}

Eltip bermek:


POST https://rgs. example/journal
Headers: X-Signature: sha256=..., X-Trace-Id: tr_a1b2
{
"event_type":"wallet. credit. ok",  "schema_version":"1. 2. 0",  "event_id":"uuid",  "payload":{"player_id":"p_19f3","amount":{"minor_units":1460,"currency":"EUR"}}
}

4) Idempotentlik we ylalaşyklylyk

Write-amallarda elmydama 'X-Idempotency-Key' -ni talap ediň (REST/gRPC metadata). Gaýtalamak → Şol jogap.

Açaryň düzümi iş parametrlerine baglydyr (mysal üçin 'bet _ id + amount').

Uzyn amallar üçin saglar (authorize → commit/lock → settle → credit).

Outbox/CDC: wakalar geleşigiň gapdalynda atomiki ýazylýar we daşardan çap edilýär.

5) Wersiýalaşdyrmak we gabat gelmek

REST - '/v1/... '+' Deprecation/Sunset '-başlyklar; gRPC — `package wallet. v1`; wakalar - 'schema _ version' bedenlerde + shemalaryň sanawy.

SemVer: minor - optional meýdanlary/täze endpoints; major - täze ýol/paket, migrasiýadaky wakalaryň "goşa haty".

Maýor wersiýasy bolmazdan pul statusynyň semantikasyny hiç haçan üýtgetmäň.

6) Ulag howpsuzlygy

mTLS ähli S2S; webhuklar üçin - bedeniň goly (HMAC/EdDSA) + timestamp we tassyklama penjireleri.

Satyn alyş çäkleri (OAuth2 CC) we açar segmentleri per brand/region.

Zero-trust: tor syýasatlary, gysga ömürli bellikler, Vault/HSM, WORM-kritiki hereketleriň barlagy.

7) Synlamak we SLO

'trace _ id' arkaly REST, gRPC metadata we webhuklarda.

Metrikler: p50/p95/p99 latency, error rate kodlar boýunça, throughput, lag nobatlar.

SLO minimum:

Wallet p95 '<150 ms' (Authorize/Settle), REST köpçülige açyk B2B p95 '<300 ms', Webhuklar gowşuryldy '<5 min' 99-njy percentil, "Lost/dubl settlementler" = 0.

8) Retraýlar, backoff we eltip bermegiň tertibi

REST/gRPC: eksponensial backoff, jitter, wagt çäkleri (deadline/timeout).

Webhuklar: '2xx' -e çenli gaýtalanýan eltip bermek; açar tertibini saklamak ('player _ id/round _ id') ýa-da kabul edijide duplikasiýa.

Anti-tupanlar: paralel retraýlaryň çäkleri, circuit breaker, rate limit.

9) Integrasiýa patternleri

Pattern A: "Pul sinhron, wakalar asinhron"

1. RGS → Wallet (gRPC/REST) `authorize` → `settle/credit`.

2. Şol bir wagtyň özünde 'bet' çap edilýär. settled 'tekerde, üpjün ediji bolsa webhuk-kwitansiýany alýar.

Goşmaça: çalt pul, gözegçilik. Minus: iki kontur gerek.

Pattern B: "Streaming live"

gRPC akymy arkaly Live Bridge ýadrosy (stoluň ýagdaýy, jedel penjiresi).

Pul amallary - aýry-aýry unary RPC; wakalar - şine/webhuka.

Goşmaça: diri statuslaryň iň az gijikdirilmegi.

Pattern C: "B2B Public REST"

Kataloglar/bonuslar/affiliates/hasabatlar - cursor-paginasiýa, süzgüçler, ETag bilen REST.

Goşmaça: hyzmatdaşlaryň ýönekeý integrasiýasy.

10) Anti-pattern (gyzyl baýdaklar)

Pul amallary diňe webhuklar arkaly (sinhron tassyklamasyz).

"Idempotency-Key" → iki sany debet/karzyň ýoklugy.

Wakalary outbox/CDC-den aýlanyp geçirmek (wakalar ýitýär).

Gol/wagt belligi bolmadyk webhuklar → çalyşmak.

Dürli sebitleriň PII/pullaryny bir kanalda 'region/tenant' belligi bolmazdan garyşdyrmak.

Webhuklarda uly binary payload (retralary we çäkleri bozýar).

Nol zaýalanmalar: webhuklaryň ýykylmagy puluň hasaplanmagyny bökdeýär.

gRPC deadline we backoff bolmasa - asylan baglanyşyklar, çeşmeleriň tükenmegi.

11) Çek-listler

Arhitektor/platforma

gRPC/REST boýunça pul, wakalar - webhuk/teker.
Ähli pul ýollarynda Outbox/CDC.
`/vN` и schema registry; Deprecation/Sunset prosesi.
mTLS + webhook gollary; sekretler per brand/region.
SLO-daşbordlar p95/p99, error rate, webhook-lag.
DR/xaoc-maşklar: goşa eltip bermek, out-of-order, sebitiň galyndylary.

Üpjün ediji/RGS

Iberýärin 'X-Trace-Id' we 'X-Idempotency-Key'.
Backoff we de-duplikasiýa bilen retrailer; webhuklary gaýtadan eltmäge taýýar.
Şertnamalaryň wersiýalaryny täzeleýärin; 'Deprecation/Sunset' -e reaksiýa bildirýärin.
Ýalňyşlyk we wagt kodlary boýunça girişler/metrikler.

12) Ýiti ýagdaýlar üçin kiçi çözgütler

Safari/ITP we third-party çäklendirmeleri: pul - hostda (REST/gRPC), iFrame-mazmuny 'postMessage' arkaly aragatnaşyk saklaýar; iFrame-den däl-de, hostdan webhuklar.

Multibrand: başlyklarda we wakalarda 'tenant _ id/brand _ id/license' bellikleri; açarlar/şahadatnamalar aýrylýar.

Uly partlamalar (ýaryşlar): webhuklaryň öňünde - DLQ bilen bufer/nobat; artykmaç ýüklenende - "no new sessions "/" pause non-core hooks".

13) SLO gönükdirilen alertleriň mysallary

Wallet. Authorize p95> 150 ms 5 minut yzly-yzyna.

Ýalňyşlyklar 'DUPLICATE/IDEMPOTENCY _ MISMATCH'> 0. 10 minutda 5%.

Webhook lag p99> 180 c tema boýunça 'bet. settled`.

Kafkadaky ulanyjy lag> 30 s üçin 'wallet. credit.`.

14) Netije

REST, gRPC we iGaming-daky webhuklar biri-biriniň ornuny tutýan tehnologiýalar däl-de, eýsem bir operasiýa modeliniň bölekleridir.

REST/gRPC pul üýtgemelerini saklaýar: pes gizlinlik, idempotentlik, berk SLA.

Webhuklar/tekerler aç-açanlygy we gerimi üpjün edýär: wakalar, telemetriýa, integrasiýa.

Outbox/CDC, wersiýa, gollar we gözegçilik - we pul çalt we howpsuz hereket edýän arhitektura alyň, wakalar ýitmeýär we täzelenmeler agyrysyz geçýär.