REST, gRPC and Webhooks in iGaming: Patterns and Anti-Patterns

Full article

💡 18+. Technical material for iGaming product and engineering teams. Not a call to play. By "platform" we mean PAM/wallet/cash register/bonuses/RG. "Provider" - RGS/live/jackpots/aggregators.

1) Protocol map: who is responsible for what

REST - universal synchronous requests over HTTP/JSON. Transparent cache, simple debugging, convenient for B2B integrations and admin API.

gRPC - high-performance binary RPC over HTTP/2: low latency, streams, hard circuits. Good for hot money paths (wallet/settle), internal services and long-lived streams (live).

Webhooks are callbacks from the recipient to the sender. Used for events ("the money fell," "the limit worked"), where the initiator is not always the one who is waiting for the result.

Golden rule:

Money goes on synchronous RPC (REST/gRPC) with hard invariants and idempotency. Telemetry and business events - asynchronously (webhooks + event bus).

2) Typical paths and recommended channels

Way	It is recommended	Why
`bets. authorize` (hold)	gRPC (internal )/REST (B2B)	minimal latency, strict SLAs
`bets. settle` → `wallet. credit`	gRPC synchronous + event to bus	money = ACID; events = observability
`cashier. deposit/withdraw`	REST + idempotency	integration with PSP, tracing
`RG check / stop`	gRPC/REST synchronous	brake lights should go off instantly
`bonus. issue/consume`	REST synchronous	business logic, moderate SLAs
`jackpot. trigger/payout`	gRPC/REST + Event	money contract + audit
Telemetry, analytics, alerts	Webhooks + Bus (Kafka/Pulsar)	sustainability and scale
Live Status/Directories	gRPC streaming / Server-Sent Events	minimizing polls and lags

3) Contract-oriented design

3. 1 REST (fragments)


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

Errors (single schema):


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

3. 2 gRPC (protobuf, simplified)

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 Webhooks (subscription example)


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

Delivery:


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) Idempotency and consistency

Always require'X-Idempotency-Key 'on write operations (REST/gRPC metadata). The replay → the same answer.

Key composition is tied to business parameters (for example, 'bet _ id + amount').

Sagas for long processes (authorize → commit/lock → settle → credit).

Outbox/CDC: Events are captured atomically near the transaction and published externally.

5) Versioning and compatibility

REST - '/v1/... '+' Deprecation/Sunset '-heads; gRPC — `package wallet. v1`; events - 'schema _ version'in bodies + schema registry.

SemVer: minor - optional/new endpoints fields; major - a new path/package, a "double letter" of events on the migration.

Never change the semantics of monetary statuses without a major version.

6) Safety of transports

mTLS on all S2S; for webhooks - body signature (HMAC/EdDSA) + timestamp and validity windows.

Scope restriction (OAuth2 CC) and per brand/region key segmentation.

Zero-trust: network policies, short-lived tokens, Vault/HSM, WORM audit of critical actions.

7) Observability and SLO

End-to-end 'trace _ id' in REST, gRPC metadata and webhooks.

Metrics: p50/p95/p99 latency, error rate by codes, throughput, lag queues.

SLO minimum (landmarks):

Wallet p95 '<150 ms' (Authorize/Settle), REST public B2B p95 '<300 ms', Webhooks delivered '<5 min' 99th percentile, "Lost/Duplicated Settlements" = 0.

8) Retrai, backoff and delivery order

REST/gRPC: exponential backoff, jitter, duration limit (deadline/timeout).

Webhooks: repeatable delivery to '2xx'; keeping order by key ('player _ id/round _ id') or deduplication at the receiver.

Anti-storms: parallel retreat limit, circuit breaker, rate limit.

9) Integration patterns

Pattern A: "Money synchronous, events asynchronous"

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

2. In parallel, 'bet is published. settled 'to the bus, and the provider receives a webhook receipt.

Plus: fast money, observability. Minus: you need two contours.

Pattern B: "Streaming live"

Live-core ↔ Bridge via gRPC streaming (table statuses, betting window).

Cash transactions - separate unary RPC; events - in the bus/webhooks.

Plus: minimal delay of live statuses.

Pattern C: "B2B public REST"

Catalogs/bonuses/affiliates/reports - REST with cursor pagination, filters, ETag.

Plus: simple partner integration.

10) Anti-patterns (red flags)

Cash transactions only through webhooks (without synchronous confirmation).

No 'Idempotency-Key' → duplicate debits/credits.

Publishing events bypassing outbox/CDC (events are lost).

Unsigned/timestamped webhooks → substitution.

Mixing PII/money of different regions in one channel without 'region/tenant' tags.

Large binary payload in webhooks (break retrays and limits).

Zero degradation: the fall of webhooks blocks the calculation of money.

gRPC without deadline and without backoff - stuck connections, resource exhaustion.

11) Checklists

Architect/Platform

Money by gRPC/REST with idempotency, events - webhooks/bus.
Outbox/CDC on all money paths.
`/vN` и schema registry; Deprecation/Sunset process.
mTLS + webhook signatures; secrecies per brand/region.
SLO-dashboards p95/p99, error rate, webhook-lag.
DR/xaoc-exercises: double-delivery, out-of-order, dump of the region.

Provider/RGS

Sending 'X-Trace-Id' and 'X-Idempotency-Key'.
Backoff and deduplication retreas; is ready to re-deliver webhooks.
Update contract versions; reacting to 'Deprecation/Sunset'.
Logs/metrics by error code and time.

12) Mini solutions for sharp cases

Safari/ITP and third-party restrictions: money - in the host (REST/gRPC), iFrame content communicates via 'postMessage'; webhooks from a host other than iFrame.

Multi-brand: tags' tenant _ id/brand _ id/license'in headers and events; keys/certificates are separate.

Large bursts (tournaments): before webhooks - buffer/queue with DLQ; when overloaded - "no new sessions "/" pause non-core hooks."

13) Examples of SLO-oriented alerts

Wallet. Authorize p95> 150 ms 5 min in a row.

'DUPLICATE/IDEMPOTENCY _ MISMATCH'errors> 0. 5% in 10 min.

Webhook lag p99> 180 c on theme 'bet. settled`.

Consumer lag at Kafka> 30 s for'wallet. credit.`.

14) Withdrawal

REST, gRPC and webhooks in iGaming are not interchangeable technologies, but parts of the same operating model.

REST/gRPC are held by monetary invariants: low latency, idempotency, strict SLAs.

Webhooks/bus provide transparency and scale: events, telemetry, integrations.

Add outbox/CDC, versioning, signatures and observability - and get an architecture where money moves quickly and safely, events are not lost, and upgrades are painless.