REST, gRPC жана iGaming Webhook: үлгүлөрү жана анти-үлгүлөрү

Макаланын толук тексти

💡 18+. iGaming азык-түлүк жана инженердик командалар үчүн техникалык материалдар. оюнга чакыруу эмес. "Платформа" деп PAM/капчык/касса/бонустарды/RG билдирет. "Провайдер" - RGS/live/джекпот/агрегаторлор.

1) Протоколдордун картасы: ким эмне үчүн жооптуу

REST - HTTP/JSON боюнча универсалдуу синхрондуу суроо. Ачык кэш, жөнөкөй оңдоо, B2B интеграциясы жана админ-API үчүн ыңгайлуу.

gRPC - HTTP/2 үстүндөгү жогорку өндүрүмдүү экилик RPC: төмөн латенттүүлүк, агымдар, катуу схемалар. Ысык акча жолдору (wallet/settle), ички кызматтар жана узак мөөнөттүү агымдар (live) үчүн жакшы.

Вебхактар - алуучудан жөнөтүүчүгө кайтарым чалуулар (callback). Иш-чаралар үчүн колдонулат ("акча түштү", "лимит иштеди"), мында демилгечи дайыма эле жыйынтыкты күткөн адам боло бербейт.

Алтын эреже:

Акча катуу инварианттар жана демпотенттүүлүк менен синхрондуу RPC (REST/gRPC) боюнча барат. Телеметрия жана бизнес-окуялар - асинхрондук (вебхактар + шина окуялар).

2) Типтүү жолдор жана сунушталган каналдар

Жол	Сунушталган	Эмне үчүн
`bets. authorize` (hold)	gRPC (ичинде )/REST (B2B)	минималдуу жашыруун, катуу SLA
`bets. settle` → `wallet. credit`	gRPC синхрондуу + шина окуя	акча = ACID; окуялар = байкоо
`cashier. deposit/withdraw`	REST + ыктымалдуулук	PSP менен бириктирүү, соода
`RG check / stop`	gRPC/REST синхрондуу	токтоо сигналдары дароо иштеши керек
`bonus. issue/consume`	REST синхрондуу	бизнес-логика, орточо SLA
`jackpot. trigger/payout`	gRPC/REST + окуя	акча келишими + аудит
Телеметрия, аналитика, алерталар	Webhuke + шина (Kafka/Pulsar)	туруктуулугу жана масштабы
Live статусу/каталогдору	gRPC streaming / Server-Sent Events	сурамжылоо жана лагдарды азайтуу

3) Келишим багытталган дизайн

3. 1 REST (үзүндүлөр)


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"}

Каталар (бирдиктүү схема):


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

3. 2 gRPC (protobuf, жөнөкөйлөштүрүлгөн)

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 Вебхактар (жазылуунун мисалы)


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

Жеткирүү:


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) Идемпотенттүүлүк жана ырааттуулук

Ар дайым write-операцияларында 'X-Idempotency-Key' талап (REST/gRPC metadata). кайталоо → ошол эле жооп.

Ачкычтын курамы бизнес параметрлерине байланыштуу (мисалы, 'bet _ id + amount').

Узак процесстер үчүн сагалар (authorize → commit/lock → settle → credit).

Outbox/CDC: Окуялар транзакциянын жанында атомдук түрдө жазылып, сырттан жарыяланат.

5) Версия жана шайкештиги

REST - '/v1/... '+' Deprecation/Sunset '-заголовкалары; gRPC — `package wallet. v1`; окуялар - 'schema _ version' денелерде + схемалар реестри.

SemVer: minor - талаа optional/жаңы endpoints; major - жаңы жол/пакет, миграция боюнча окуялардын "кош каты".

Эч качан негизги версиясы жок акча статусунун семантикасын өзгөртпөңүз.

6) Транспорт коопсуздугу

mTLS бардык S2S; вебхуктар үчүн - дененин кол тамгасы (HMAC/EdDSA) + timestamp жана тактык терезелери.

Сатып алууларды чектөө (OAuth2 CC) жана per brand/region ачкычтарын сегменттөө.

Zero-trust: тармактык саясатчылар, кыска мөөнөттүү токендер, Vault/HSM, WORM-аудит сын иш-аракеттер.

7) Байкоо жана SLO

Аркылуу 'trace _ id' REST, gRPC metadata жана вебхуктарда.

Метрика: p50/p95/p99 latency, error rate коддору, throughput, lag кезек.

SLO-минималдуу

Wallet p95 '<150 ms' (Authorize/Settle), REST коомдук B2B p95 '<300 ms', Webhuke жеткирилди '<5 мин' 99-перцентил, "Жоголгон/кайталанган сеттлменттер" = 0.

8) Retrains, backoff жана жеткирүү тартиби

REST/gRPC: экспоненциалдуу backoff, життер, узактыгын чектөө (deadline/timeout).

Webhook: '2xx' чейин кайталап жеткирүү; ачкыч тартибин сактоо ('player _ id/round _ id') же кабыл алуучуда дедупликация.

Анти-бороон: параллелдүү retrains чеги, circuit breaker, rate limit.

9) Интеграция үлгүлөрү

Паттерн А: "Акча синхрондуу, окуялар асинхрондук"

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

2. Ошол эле учурда жарыяланган 'bet. settled 'шинага, ал эми провайдер вебхук квитанциясын алат.

Plus: тез акча, байкоо. Минус: эки контур керек.

Pattern B: "Streaming Live"

gRPC агым аркылуу Live-ядро Bridge (стол статусу, коюм терезе).

Акча операциялары - өзүнчө unary RPC; окуялар - шина/Webhuke.

Plus: тирүү статусун минималдуу кечигүү.

C үлгүсү: "B2B коомдук REST"

Каталогдор/бонустар/аффилиаттар/отчеттор - cursor-pagination, чыпкалар, ETag менен REST.

Плюс: өнөктөштөрдүн жөнөкөй интеграциясы.

10) Анти-үлгүлөрү (кызыл желектер)

Акча операциялары вебхактар аркылуу гана (синхрондуу тастыктоосуз).

Жок 'Idempotency-Key' → эки эселенген дебеттер/кредиттер.

outbox/CDC айланып окуялар жарыялоо (жоголгон окуялар).

Кол тамгасыз/убакыт белги → алмаштыруу.

Бир каналда ар кайсы аймактардын PII/акчасын 'region/tenant' деген тегсиз аралаштыруу.

Вебхуктардагы чоң binary payload (ретраларды жана лимиттерди бузат).

Нөлдүк деградация: вебхуктардын кулашы акчаны эсептөөгө бөгөт коёт.

gRPC deadline жана backoff жок - илинип байланыштар, ресурстардын түгөнүшү.

11) Чек-баракчалар

Архитектор/платформа

Демпотенттик менен gRPC/REST боюнча акча, иш-чаралар - Webhuke/шина.
бардык акча жолдорунда Outbox/CDC.
`/vN` и schema registry; Deprecation/Sunset жараяны.
mTLS + вебхуктардын кол тамгалары; secrets per brand/region.
SLO-dashboard p95/p99, error rate, webhook-lag.
DR/xaoc-машыгуулар: кош-жеткирүү, out-of-order, аймактын калдыктары.

Провайдер/RGS

жөнөтүү 'X-Trace-Id' жана 'X-Idempotency-Key'.
backoff жана дедупликация менен Retray; вебхуктарды кайра жеткирүүгө даяр.
Мен келишимдердин версияларын жаңыртам; жооп "Deprecation/Sunset".
каталар жана убакыт коддору боюнча Логи/метрика.

12) курч учурларда үчүн Mini Solutions

Safari/ITP жана third-party чектөөлөрү: акча - хостте (REST/gRPC), iFrame мазмуну 'postMessage' аркылуу байланышат; Вебхукс хостинг эмес, iFrame.

Multibrand: tags 'tenant _ id/brand _ id/license' аталыштары жана окуялар; ачкычтары/күбөлүктөрү өзүнчө.

Чоң жарылуу (турнирлер): вебхуктардын алдында - DLQ менен буфер/кезек; ашыкча жүктөөдө - "no new sessions "/" pause non-core hooks".

13) SLO багытталган Алерт мисалдар

Wallet. Authorize p95> 150 мс катары менен 5 мин.

Каталар 'DUPLICATE/IDEMPOTENCY _ MISMATCH'> 0. 5% 10 мин.

Webhook lag p99> 180 c тема 'bet. settled`.

Consumer lag үчүн Kafka> 30 с 'wallet. credit.`.

14) Жыйынтык

REST, gRPC жана iGaming веб-хаки бири-бирин алмаштыруучу технологиялар эмес, бир операциялык моделдин бөлүктөрү.

REST/gRPC акча инвариантын кармап турат: төмөн латенттүүлүк, демпотенттүүлүк, катуу SLA.

Webhook/шина ачык-айкындуулугун жана масштабын камсыз кылат: окуялар, телеметрия, бириктирүү.

Outbox/CDC кошуу, нускалоо, кол тамгалар жана байкоо - жана акча тез жана коопсуз жылып турган архитектура алуу, иш-чаралар жоголгон эмес, жана апгрейд оорутпай өтөт.