REST , e webhook nel : pattern e anti-pattern

Testo completo dell'articolo

💡 18+. Materiale tecnico per i team di alimentari e ingegneria. Non una chiamata al gioco. Per «piattaforma» si intende PAM/portafoglio/cassa/bonus/RG. Provider - RGS/live/jackpot/aggregatori.

1) Mappa dei protocolli: chi è responsabile di cosa

REST- Query sincrono universali HTTP/JSON. Semplice debug e trasparente per integrazioni B2B e admine-API.

gRPC - RPC binario ad alte prestazioni sopra HTTP/2: bassa latitanza, striam, diagrammi rigidi. Buono per le vie di cassa hot (wallet/settle), servizi interni e striam a lunga vita (live).

Webhook - Chiamate di ritorno (callback) da destinatario a mittente. Usati per eventi («il denaro è sceso», «il limite ha funzionato»), dove l'iniziatore non è sempre uno che aspetta il risultato.

Regola d'oro:

I soldi vanno a RPC sincronizzato (REST/gRPC) con invarianti rigidi e idipotenti. Telemetria e eventi aziendali - asincrona (webhoop + bus eventi).

2) Percorsi tipici e canali consigliati

Percorso	Raccomandato	Perché
`bets. authorize` (hold)	gRPC (interno )/REST (B2B)	latitanza minima, SLA rigorosi
`bets. settle` → `wallet. credit`	gRPC sincrono + evento pneumatico	denaro = ACID; eventi = osservabilità
`cashier. deposit/withdraw`	REST+ idampotenza	integrazione con PSP, training
`RG check / stop`	gRPC/REST sincrono	i segnali di arresto devono scattare immediatamente
`bonus. issue/consume`	RESTON sincrono	logica aziendale, moderata SLA
`jackpot. trigger/payout`	gRPC/REST + evento	contratto di cassa + controllo
Telemetria, analista, alert	Webhook + pneumatico (Kafka/Pulsar)	sostenibilità e scala
Stato/directory live	gRPC streaming / Server-Sent Events	Ridurre al minimo i sondaggi e le corse

3) Design incentrato sul contratto

3. 1 REST (sezioni)


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

Errori (diagramma unico):


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

3. 2 gRPC (protobuf, semplificato)

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 Webhook (esempio di sottoscrizione)


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

Consegna:


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) Idampotenza e coerenza

Richiedi sempre «X-Idempotency-Key» nelle operazioni write (REST/gRPC metadata). La ripetizione è la stessa.

La composizione della chiave è associata ai parametri aziendali (ad esempio, 'bet _ id + amount').

Saghe per processi lunghi (authorize → commit/lock → settle → credit).

Outbox/CDC: gli eventi vengono registrati atomicamente accanto alla transazione e pubblicati dall'esterno.

5) Versioning e compatibilità

REST- '/v1/... '+' Deprecation/Sunset '- zampe; gRPC — `package wallet. v1`; eventi - 'schema _ version'nei corpi + registro degli schemi.

SemVer: minor - campi optional/nuovi endpoint; major - nuovo percorso/pacchetto, «doppia lettera» degli eventi sulla migrazione.

Non cambiare mai la semantica degli stati in denaro senza la versione maggiore.

6) Sicurezza dei trasporti

mTLS su tutti i S2S; per i webhoop - firma del corpo (HMAC/EdDSA) + timestamp e finestre di validità.

Vincolo scoop (OAuth2 CC) e segmentazione chiavi per brand/region.

Zero-trust: regole di rete, token a breve vita, Vault/HSM, controllo WORM delle attività critiche.

7) Osservabilità e SLO

Trace _ id (trace _ id) in RESTA, metadata e webhoop.

Metriche: p50/p95/p99 latency, error rate per codice, throughput, code.

SLO-minimo (punti di riferimento):

Wallet p95 '<150 ms' (Authorize/Settle), REST B2B p95 '<300 ms', Webhook' <5 min '99,' Settementi persi/duplicati '= 0.

8) Retrai, backoff e ordine di consegna

REST/gRPC: backoff esponenziale, jitter, limite di durata (deadline/timeout).

Webhook: spedizione ripetuta fino a «2xx»; salvataggio dell'ordine in chiave ('player _ id/round _ id') o deduplicazione nel ricevitore.

Anti-tempeste: limite di retrai paralleli, circuito breaker, rate limit.

9) Modelli di integrazione

Pattern A: «Denaro sincronizzato, eventi asincrono»

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

2. In parallelo viene pubblicato'bet. settled'nel pneumatico e il provider riceve una ricevuta webhook.

In più, soldi veloci, osservabilità. Meno, ci servono due tracciati.

«Streaming live» di Pattern B

Il kernel live di Bridge attraverso lo streaming (stato del tavolo, finestra delle scommesse).

Transazioni in denaro - singole RPC unary; eventi - in un bus/webhook.

Inoltre, il ritardo minimo degli stati viventi.

Pattern C: «B2B pubblico REST»

Cataloghi/bonus/affiliati/report - RESTA con paginazione cursor, filtri, ETag.

Inoltre, la semplice integrazione dei partner.

10) Anti-pattern (bandiere rosse)

Transazioni di denaro solo tramite webhoop (senza conferma sincrona).

L'assenza di «Idempotency-Key» è una ripresa di debiti/crediti.

Pubblicare eventi che aggirano outbox/CDC (si perdono eventi).

Webhoop senza firma/etichetta temporale del cambio.

Miscelare PII/denaro di diverse regioni in un unico canale senza tag «region/tenant».

Grandi binary payload in webhoot (rompono retrai e limiti).

Zero degrado, la caduta dei webhoot blocca il calcolo dei soldi.

gRPC senza deadline e senza backoff - connessioni dipendenti, esaurimento delle risorse.

11) Assegno fogli

Architetto/piattaforma

Soldi per idoneità, eventi - webhook/pneumatico.
Outbox/CDC su tutti i percorsi di cassa.
`/vN` и schema registry; Deprecation/Sunset processo.
mTLS + firma webhoop; segmenti per brand/region.
SLO-dashboard p95/p99, error rate, webhook-lag.
DR./xaoc-esercitazioni: scatto-consegna, out-of-order, fuori regione.

Provider/RGS

Invio «X-Trace-Id» e «X-Idempotency-Key».
Retrai con backoff e deduplicazione Pronto per la nuova consegna dei webhoot.
Aggiorna le versioni dei contratti; Reagisco a Deprecation/Sunset.
Logi/metriche per codici di errore e tempo.

12) Mini-soluzioni per valigette affilate

Safari/ITP e third-party limitazioni: denaro - in host (REST/gRPC), iFrame-Content comunica attraverso «postMessage»; webhoop da host, non da iFrame.

Multibrand: tag «tenant _ id/brand _ id/license» in intestazioni ed eventi; chiavi/certificati separati.

Grandi picchi (tornei): prima dei webhoop - buffer/coda con DLQ; quando si sovraccarica, «no new sessions »/» pausa non-core hooks».

13) Esempi di alert orientati a SLO

Wallet. Authorize p95> 150 ms 5 min consecutive.

Errori dì DUPLICATO/IDEMPOTENCY _ MISMATCH '> 0. 5% in 10 minuti

Webhook lag p99> 180 c su "bet. settled`.

Consumer lag in Kafka> 30 c per 'wallet. credit.`.

14) Output

RESTE, e webhoop non sono tecnologie interscambiabili, ma parti dello stesso modello operativo.

REST/gRPC tengono invarianti in denaro, bassa latitanza, idampotenza, SLA rigorosi.

Webhook/bus garantiscono trasparenza e scala: eventi, telemetria, integrazione.

Aggiungi outbox/CDC, versioning, firme e osservabilità - e ottieni un'architettura dove il denaro si muove in modo rapido e sicuro, gli eventi non si perdono e gli upgrade passano indolore.