Automatización de eventos y premios: reglas y webhooks

La gamificación se sostiene en dos «motores»: los eventos (lo que hizo el usuario) y las reglas (lo que se debe). Para que esto funcione a gran escala y sin errores, necesita un bus de eventos confiable, un motor de reglas, un mecanismo de entrega/entrega de recompensas y una estricta protección contra el frod. A continuación, arquitectura práctica, plantillas y listas de cheques.

1) Arquitectura de flujo «evento → regla → recompensa»

1. Ingest (Inicio de sesión de eventos): SDK/Web, Webhooks de servidor de un jugador/proveedor de juegos → API Gateway → cola/bus (Kafka/Rabbit/Cloud Pub/Sub).

2. Normalizador: validación, enriquecimiento (geo, dispositivo, payer_flag), versión del circuito.

3. Rules Engine: puntuación de puntos/HR, verificación de misiones/misiones, desencadenantes de recompensas/notificaciones.

4. Reward Orchestrator: cálculo de recompensas, presupuesto-cheque, RG/KYC-Gates, creación de «tareas de emisión», registro.

5. Payout/Bonus Service: caché/bonus cache/freespins/cupones, webhooks externos (billetera, proveedores).

6. Notifier: push/in-app/email/messenger con límites de frecuencia.

7. Storage/Analytics: eventos crudos, escaparates, A/B, alertas.

8. Anti-Fraud/RG: caps, heurísticas/ML, hold-and-review de grandes premios.

2) Modelo de eventos (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 reglas: cómo describir la lógica

Conceptos: reglas (if/then), segmentos, ventanas de tiempo, caps, prioridades, versioning.

Ejemplo de regla declarativa (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: integración servidor-servidor

4. 1. Webhooks salientes (de usted a los proveedores/billetera)

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

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

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

Idempotency: la repetición del mismo 'X-Request-Id' → socio está obligado a responder con el mismo 'payout _ id/status'.

Ejemplo 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 entrantes (a usted)

Sólo permita las listas IP/MTLS, verifique el HMAC y el tiempo de vida de la firma («X-Timestamp», ± 5 minutos).

Mantenga el cuerpo «crudo» + encabezados en el almacén de auditoría (WORM).

Cualquier toma/repetición → compruebe la clave idempotency contra la revista.

5) Fiabilidad: flujo «uniforme» sin pagos dobles

Los controladores At-least-once en ingest + idempotent → el estándar de oro.

Idempotency key: 'hash (event_id + user_id + rule_id)' para ganar puntos; una clave separada para emitir la recompensa 'reward _ task _ id'.

Exactly-once semántica es realista sólo lógicamente (a través de la idempotencia), no por transporte.

Orden de eventos: almacena 'event _ ts' e' ingest _ ts'; aplique redering window (por ejemplo, 60 segundos) y replay desde la cola por clave 'user _ id'.

Dead Letter Queue (DLQ):

Escribimos allí mensajes con un error permanente (el esquema temporal no ha pasado, la firma no es válida, el presupuesto está cerrado).
Servicio de «rugido DLQ» con botones reprocess/drop/fix schema.

6) Presupuestos y protección de márgenes

Los grupos de presupuestos son: 'nat _ season', 'daily _ sprint', 'vip _ weekend'.

Cuotas: soft/hard cap, «circuit breaker» - cuando se alcanza el 90% del presupuesto para transferir grandes premios a hold-state.

Precio único: 'Prize & Bonus Cost per Active/Payor', Net Uplift.

Prioridades: RG y cumplimiento es más importante que la promoción - en caso de conflicto, la recompensa se pospone.

Ejemplo de validación de presupuesto (SQL-sketch):

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 (seguridad del jugador y cumplimiento)

KYC: mínimo L2 para caché/grandes premios; las frispinas son admisibles con L1.

RG: verificación de los límites de depósito, autoexclusión, «cool-off» → recompensas «congeladas» hasta que se levanten las restricciones.

Geo: lista de países permitidos para cada regla/grupo de premios.

Alertas de umbral: un fuerte crecimiento de «casi-alcanzado» en cuentas individuales = una razón para hold & review.

8) Reglas antifraude y telemetría

Gafas por apuesta/min/hora/día, varianza mínima de apuestas, prohibición de patrones «perfectos».

Señales: headless, device_fp repetitivas, subconjuntos proxy.

Anomalías: «puntos/apuestas» y «puntos/min» - largas «colas» en 99-percentil.

Hold-and-review para los mejores medallistas: cheque automático KYC + vista manual.

9) Monitoreo, métricas y alertas

SLO/SLA:

Ingest p95 ≤ 250 ms; procesamiento de la regla p95 ≤ 150 ms; actualización del tablero de liderazgo ≤ 2 s; emisión de un premio ≤ 60 s.
Error budget < 0. 1% de eventos/día.

Alertas:

SRM en experimentos (distorsión del tráfico), crecimiento de DLQ, caída de la firma de validación HMAC, exceso de presupuesto, aumento de idempotent-tomas.

Dashboard (diario):

Eventos/s, log, tolerancia a fallas;
El embudo: el acontecimiento → la regla → reward_task → reward_issued;
Costo: Prize/Bonus per Active, Net Uplift;
Calidad: banderas de Frod, unidades KYC, RG-activación.

10) Versificación y migración

Cada regla es versioned ('reglas. version`).

No se puede editar una regla activa sin una nueva versión; use fichflag y «calentamiento suave» (10% → 50% → 100%).

Esquema de eventos a través del registro schema; cambios incompatibles - versión mayor solamente.

11) Pruebas de automatización A/B (corto)

Unidad - Usuario; sticky-assignment; estratificación (payer/geo/plataforma).

Liderazgos separados o normalización de puntos para descartar interferencias.

Primary: participation_net, completion, Net ARPPU; Guardrails: quejas/1k, banderas de Frod, RG-activación.

CUPED y covariables para reducir la dispersión.

12) Ejemplos: desde la regla hasta la extradición

12. 1. El detonante del «micro premio al progreso»

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 saliente en la billetera


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

El éxito → 'reward _ task' = 'succeeded' y la entrada en 'reward _ ledger'.

El fracaso (5xx/taimout) → un retray con el mismo 'X-Request-Id'.

Fallo (4xx) → DLQ + análisis manual.

13) Almacenes y tablas (sketch)

sql
-- revista de premios
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
);

-- indempotencia
CREATE UNIQUE INDEX uniq_reward_task ON reward_ledger (reward_task_id);

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

14) Seguridad y privacidad

Firmas HMAC, MTLS, allow-list IP.

Encriptación en tránsito/descanso, rotación de claves, secretos en vault.

Minimizar los datos en payload (PII por separado, por enlace token, TTL).

Los registros de auditoría son inmutables (WORM).

Política de retención y eliminación (derecho al olvido, deduplicación segura).

15) Lista de comprobación de inicio

Esquemas de eventos y registro, contratos de webhooks (firmas, TTL).
Colas, retraídas, DLQ, manejadores idempotentes.
Caps/guardaires en las reglas, KYC/RG-gates.
Presupuesto-pools, circuit-breakers, alertas de desbordamiento.
Dashboard SLO + embudo reward.
A/B-fichflags y monitoreo SRM.
Runbook de incidentes (reprogramación, congelación, dispensación manual).

16) Mini caso (sintético)

Eventos conectados de proveedores de juegos y billetera; incluido «win/bet» scoring con caps.

Webhooks firmados por HMAC, retraídas de hasta 8 intentos, DLQ con rugido cada 2 h.

En 4 semanas: El valor del tratamiento p95 180 ms; DLQ < 0,06%; tomas de pago 0; Banderas de Frod −0,4 p.p.; ΔParticipation_net +6,3 п.п.; ΔARPPU (net) +€2,1 при Prize&Bonus/Active +€0,7.

Conclusión: escalar las reglas a nuevos geo con grupos de presupuesto local.

La automatización de recompensas no es «enviar push con giros fríos». Es un sistema de ingeniería: entrega de eventos confiable, estricta versificación de reglas, idempotency y firmas, presupuesto-capers, KYC/RG gates, antifraude y monitoreo. Construya este marco un día - y cualquier misión, torneo y «lot-moments» funcionará previsiblemente, a tiempo y con un efecto neto positivo.