REST, gRPC і вебхуки в iGaming: патерни та анти-патерни

Повний текст статті

💡 18+. Технічний матеріал для продуктових та інженерних команд iGaming. Не заклик до гри. Під «платформою» маємо на увазі PAM/гаманець/касу/бонуси/RG. «Провайдер» - RGS/live/джекпоти/агрегатори.

1) Карта протоколів: Хто за що відповідає

REST - універсальні синхронні запити по HTTP/JSON. Прозорий кеш, проста налагодження, зручний для B2B інтеграцій і адмін-API.

gRPC - високопродуктивний двійковий RPC поверх HTTP/2: низька латентність, стріми, жорсткі схеми. Хороший для гарячих грошових шляхів (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 + подія	грошовий контракт + аудит
Телеметрія, аналітика, алерти	Вебхукі + шина (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) Ідемпотентність та узгодженість

Завжди вимагайте'X-Idempotency-Key'на write-операціях (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 - новий шлях/пакет, «подвійний лист» подій на міграції.

Ніколи не змінюйте семантику грошових статусів без 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 мс'( Authorize/Settle), REST публічних B2B p95'< 300 мс', Вебхуки доставлені'< 5 хв'99-й перцентиль, «Втрачених/дубльованих сеттлментів» = 0.

8) Ретраї, backoff і порядок доставки

REST/gRPC: експоненціальний backoff, джиттер, обмеження тривалості (deadline/timeout).

Вебхуки: повторювана доставка до «2xx»; збереження порядку за ключем ('player _ id/round _ id') або дедуплікація на приймачі.

Анти-шторми: ліміт паралельних ретраїв, circuit breaker, rate limit.

9) Патерни інтеграції

Патерн A: «Гроші синхронно, події асинхронно»

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

2. Паралельно публікується'bet. settled'в шину, а провайдер отримує вебхук-квитанцію.

Плюс: швидкі гроші, спостережуваність. Мінус: потрібно два контури.

Патерн B: «Streaming live»

Live-ядро ↔ Bridge через gRPC streaming (статуси столу, вікно ставок).

Грошові операції - окремі unary RPC; події - в шину/вебхуки.

Плюс: мінімальна затримка живих статусів.

Патерн C: «B2B публічний REST»

Каталоги/бонуси/афіліати/звіти - REST з cursor-пагінацією, фільтрами, ETag.

Плюс: проста інтеграція партнерів.

10) Анти-патерни (червоні прапори)

Грошові операції тільки через вебхуки (без синхронного підтвердження).

Відсутність'Idempotency-Key'→ дублі дебетів/кредитів.

Публікація подій в обхід outbox/CDC (втрачаються події).

Вебхуки без підпису/часової мітки → підміна.

Змішування PII/грошей різних регіонів в одному каналі без тегів'region/tenant'.

Великі binary payload у вебхуках (ламають ретраї і ліміти).

Нульові деградації: падіння вебхуків блокує розрахунок грошей.

gRPC без deadline і без backoff - завислі з'єднання, вичерпання ресурсів.

11) Чек-листи

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

Гроші по gRPC/REST з ідемпотентністю, події - вебхукі/шина.
Outbox/CDC на всіх грошових шляхах.
`/vN` и schema registry; Deprecation/Sunset процес.
mTLS + підписи вебхуків; секректи per brand/region.
SLO-дашборди p95/p99, error rate, webhook-lag.
DR/xaoc-навчання: дубль-доставки, out-of-order, відвал регіону.

Провайдер/RGS

Відправляю'X-Trace-Id'і'X-Idempotency-Key'.
Ретраї з backoff і дедуплікацією; готовий до повторної доставки вебхуків.
Оновлюю версії контрактів; реагую на'Deprecation/Sunset'.
Логи/метрики за кодами помилок і часу.

12) Міні-рішення для гострих кейсів

Safari/ITP і third-party обмеження: гроші - в хості (REST/gRPC), iFrame-контент спілкується через'postMessage'; вебхукі від хоста, не від iFrame.

Мультибренд: теги'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.

Вебхуки/шина забезпечують прозорість і масштаб: події, телеметрія, інтеграції.

Додайте outbox/CDC, версіонування, підписи і спостережуваність - і отримаєте архітектуру, де гроші рухаються швидко і безпечно, події не губляться, а апгрейди проходять безболісно.