Automação de eventos e prêmios: regras e webhooks

A gaimiferização é mantida em dois «motores»: o evento (o que o usuário fez) e as regras (o que depende disso). Para que isso funcione em grande escala e sem problemas, você precisa de um pneu de evento seguro, um motor de regras, um mecanismo de entrega/emissão de prêmios e proteção rigorosa contra o from. Abaixo, arquitetura prática, modelos e folhas de cheque.

1) Arquitetura de fluxo «evento → regra → recompensa»

1. Ingest (entrada de eventos): SDK/Web, webhooks do servidor/provedor de jogos → API Gateway → fila/pneu (Kafka/Rabbit/Cloud Pub/Sub).

2. Normalizer: validação, enriquecimento (geo, device, payer _ flag), versão do esquema.

3. Rulas Engine: pontuação de pontos/HC, verificação de missões/buscas, desencadeadores de prémios/notificações.

4. Reward Orquestrator: pagamento de prémios, orçamento-cheque, RG/KYC-gates, criação de «tarefas de emissão», registro.

5. Payout/Bónus Service: dinheiro/bónus-dinheiro/cupons/cupons, webhooks externos (carteira, provedores).

6. Notifier: push/in-app/email/mensagens com limites de frequência.

7. Armazenamento/Analytics: eventos crus, vitrines, A/B, alertas.

8. Anti-Fraud/RG: caps, eurísticos/ML, hold-and-review grandes prêmios.

2) Modelo de evento (conjunto mínimo)

json
{
"event_id": "d9e8-...-5c2",  "event_name": "bet",  "version": "1. 2. 0",  "ts": "2025-10-24T11:37:21Z",  "user": {
"id": "u_123",   "geo": "TR",   "platform": "android",   "payer_flag": true,   "risk_flags": ["vp_nightly"]
},  "context": {
"session_id": "s_789",   "device_fp": "fp_...",   "ip": "203. 0. 113. 24"
},  "payload": {
"game_id": "slot_wolf",   "bet": 0. 5,   "win": 1. 25,   "currency": "EUR",   "provider": "GameCo"
}
}

Базовые типы: `login`, `session_start/end`, `bet/spin`, `win`, `deposit`, `withdraw_request`, `kyc_status_changed`, `mission_view/join/progress/complete`, `tournament_join/score/update/reward`, `reward_issued`, `rg_event`.

3) Motor de regras: como descrever a lógica

Conceitos: regras (if/then), segmentos, janelas de tempo, capas, prioridades, versionização.

Exemplo de regra declaratória (estilo YAML):

yaml rule_id: r_points_winmult_v2 when:
event_name: bet filters:
- payload. bet >= 0. 2
- user. geo in ["TR","BR","PE"]
- now between "2025-11-01" and "2025-11-30"
score:
formula: "floor((payload. win / payload. bet) 3)"
caps:
per_bet: 50 per_minute: 200 per_day: 1500 reward_trigger:
on_progress:
threshold: [100, 300, 800]
reward: [{type: "fs", value: 10}, {type: "bonus_cash", value: 2}, {type: "loot", rarity: "rare"}]
guardrails:
kyc_min_level: 2 rg_limits_ok: true budget_pool: "nov_season"
budget_soft_cap: 80000 meta:
version: "2. 0"
experiment: "scoring_ab_2025w45"

4) Webhooks: servidor de integração

4. 1. Webhooks (de você para provedores/carteira)

Método: 'POST https ://parceiro. example/payouts`

Подпись: `X-Signature: HMAC-SHA256(secret, body)` + `X-Request-Id` (idempotency).

Retrai: backoff exponencial, 'max _ retries = 8', jitter, DLQ.

Idempotency: repetição do mesmo 'X-Request-Id' → o parceiro deve responder ao mesmo 'payout _ id/status'.

Exemplo de payload:

json
{
"request_id": "rid_7f5...",  "user_id": "u_123",  "reward": {"type":"cash","amount":10. 00,"currency":"EUR"},  "reason": "milestone_300_points",  "kyc_level": 2,  "constraints": {"wagering": 0, "expiry_at": "2025-12-01T00:00:00Z"}
}

4. 2. Webhooks de entrada (a você)

Autorize apenas as listas IP/MTLS, verifique o HMAC e o tempo de vida da assinatura ('X-Timestamp', se 5 minutos).

Mantenha o «crude» body + cabeçalho no armazenamento de auditoria (WORM).

Qualquer filme/repetição → verifique idempotency key contra a revista.

5) Confiabilidade: fluxo «alinhado» sem pagamento duplo

At-least-once em ingest + processadores de idempotent → um padrão dourado.

Idempotency key: 'hash (event _ id + user _ id + rule _ id)' para obter pontos; chave separada para a premiação 'reward _ task _ id'.

A semântica exactly-once é realista apenas logicamente (via idempotidade), e não por transporte.

Ordem de eventos: guarde 'event _ ts' e 'ingest _ ts'; aplique o reordering window (por exemplo, 60 segundos) e o replay da fila da chave 'user _ id'.

Dead Letter Queue (DLQ):

Enviamos mensagens com um erro permanente (o esquema temporário falhou, a assinatura não foi feita, o orçamento foi encerrado).
Serviço de revezamento DLQ com botões reprocess/drop/fix schema.

6) Orçamentos e proteção de margens

Poulas de orçamento: 'g. _ season', 'daily _ sprint', 'vip _ semana'.

Quotas: soft/hard cap, «circuito breaker» - ao atingir 90% do orçamento transferir grandes prêmios para hold-state.

Valor único: 'Prize & Bónus Costa para Ativo/Payor', Net Uplift.

Prioridades: RG e complacência mais importante do que a promoção - no conflito, a recompensa é adiada.

Exemplo de teste de orçamento (sketch SQL):

sql
SELECT pool_id,    SUM(amount) AS spent,    budget AS limit,    SUM(amount)/budget AS fill
FROM reward_ledger
WHERE pool_id =:pool AND date(ts) = current_date
GROUP BY pool_id, budget;

7) RG/KYC/Geo-gates (segurança do jogador e da complacência)

KYC: L2 mínimo para dinheiro/grandes prêmios; frevo é permitido com L1.

RG: Verificação de limites de depósito, auto-exclusão, «cool-off» → prémios «congelados» antes que as restrições sejam removidas.

Geo: lista de países autorizados para cada regra/pool de prémios.

Alertas de liminares: o crescimento «quase-alcançado» em contas individuais = motivo para hold & review.

8) Regras antifrode e telemetria

Caps de pontos a taxa/min/hora/dia, dispersão mínima de apostas, proibição de patterns «perfeitos».

Técnicas: headless, device _ fp repetidos, proxy.

Anomalias: «pontos/apostas» e «pontos/min» - longas «caudas» em 99-percentos.

Hold-and-review para premiados: cheque automático KYC + visualização manual.

9) Monitoramento, métricas e alertas

SLO/SLA:

Ingest p95 ≤ 250 ms; processamento da regra p95 ≤ 150 ms; atualização do liderbord ≤ 2 c; condecoração ≤ 60 s.
Error budget < 0. 1% dos eventos/dia.

Alerts:

SRM em experimentos (distorção de tráfego), crescimento do DLQ, queda da assinatura de validação HMAC, excesso de orçamento, elevação da dupla idempotent.

Dashboard (diariamente):

Eventos/s, liga, resistência a falhas;
Vórtice: evento → regra → reward _ task → reward _ issued;
Custo: Prize/Bónus para Ativo, Net Uplift;
Qualidade: bandeiras de frod, blocos KYC, acionamento RG.

10) Versionização e migração

Cada regra é versioned ('rulas. version`).

Não é possível editar uma regra ativa sem uma nova versão; use o fichiflag e aquecimento suave (10% → 50% → 100%).

Esquema de eventos através da schema registry; alterações incompatíveis - apenas a versão major.

11) Testes de automação A/B (curto)

Unidade - Usuário; sticky-assignment; rateamento (payer/geo/plataforma).

Liderbords separados ou normalização de óculos para eliminar interferência.

Primary: participation_net, completion, Net ARPPU; Guardrails, queixas/1k, bandeiras de frod, acionamento RG.

CUPED e cobiçados para reduzir a dispersão.

12) Exemplos, desde a regra até a emissão

12. 1. Trigger «micro-prémio para o progresso»

json
{
"type": "reward_task. created",  "reward_task_id": "rt_456",  "user_id": "u_123",  "origin": {"rule_id":"r_points_winmult_v2","threshold":300},  "reward": {"type": "bonus_cash", "amount": 2, "currency":"EUR", "wagering": 15},  "pool_id": "nov_season",  "status": "pending",  "created_at": "2025-10-24T11:38:30Z"
}

12. 2. Webhook de saída para carteira


POST /wallet/credit
X-Request-Id: rid_7f5...
X-Timestamp: 1730061700
X-Signature: sha256=7b9a...

{ "user_id":"u_123", "amount":2. 00, "currency":"EUR", "reason":"rule:r_points_winmult_v2" }

Sucesso → 'reward _ task' = 'suceeded' e gravação em 'reward _ ledger'.

Fracasso (5xx/timeout) → retrai com o mesmo 'X-Request-Id'.

Falha (4xx) → DLQ + análise manual.

13) Armazéns e tabelas (sketch)

sql
-- registro de prémios
CREATE TABLE reward_ledger (
id BIGSERIAL PRIMARY KEY,  reward_task_id TEXT UNIQUE,  user_id TEXT,  pool_id TEXT,  type TEXT,  value NUMERIC(18,2),  currency TEXT,  cost NUMERIC(18,2) DEFAULT 0, -- реальная стоимость для P&L status TEXT, -- succeeded/failed/held created_at TIMESTAMPTZ,  updated_at TIMESTAMPTZ
);

-- Indipotência
CREATE UNIQUE INDEX uniq_reward_task ON reward_ledger (reward_task_id);

-- orçamento
CREATE TABLE reward_budget (
pool_id TEXT PRIMARY KEY,  budget NUMERIC(18,2),  spent NUMERIC(18,2),  period DATE
);

14) Segurança e privacidade

Assinaturas HMAC, MTLS, allow-list IP.

Criptografia em trânsito/paz, rotação de chaves, segredos em vault.

Minimiza os dados em payload (PII separado, no link-token, TTL).

Auditorias-logs inalteradas (WORM).

Política de armazenamento e remoção (direito ao esquecimento, dedução-safe).

15) Folha de cheque de lançamento

Esquemas de eventos e registry, contratos de webhooks (assinaturas, TTL).
Filas, retais, DLQ, processadores idumpotentes.
Caps/guardas nas regras, KYC/RG-gates.
Orçamento-pula, circuito-breakers, alertas de cheias.
Dashboard SLO + vórtice reward.
A/B-fichiflagi e monitoramento SRM.
Runbook incidentes (revezamento, congelamento, emissão manual).

16) Mini-mala (sintético)

Eventos de provedores de jogos e carteira conectados; «win/bet» está incluído.

Webhooks são assinados HMAC, retraí até 8 tentativas, DLQ com revezamento a cada 2 h.

Em 4 semanas, uma liga de processamento de p95 180 ms; DLQ < 0,06%; Duplos de pagamento 0; bandeiras de frod - 0,4 p.p; ΔParticipation_net +6,3 п.п.; ΔARPPU (net) +€2,1 при Prize&Bonus/Active +€0,7.

Conclusão: escalar as regras para novos geo com orçamento-pool local.

A automação de prémios não é «enviar um pulo de frisas». Este é um sistema de engenharia: entrega de eventos confiável, versionalização rigorosa de regras, idempotency e assinaturas, orçamento-capas, KYC/RG-gate, antifrode e monitoramento. Construa este esqueleto um dia - e todas as missões, torneios e «momentos loot» funcionarão previsivelmente, a tempo e com efeitos netos positivos.