Автоматизація подій та нагород: правила та вебхуки

Гейміфікація тримається на двох «моторчиках»: події (що зробив користувач) і правила (що за це належить). Щоб це працювало масштабно і безпомилково, потрібна надійна шина подій, рушій правил, механізм доставки/видачі нагород і суворий захист від фроду. Нижче - практична архітектура, шаблони і чек-листи.

1) Архітектура потоку «подія → правило → нагорода»

1. Ingest (вхід подій): SDK/web, серверні вебхуки від платіжки/провайдера ігор → API Gateway → черга/шина (Kafka/Rabbit/Cloud Pub/Sub).

2. Normalizer: валідація, збагачення (geo, device, payer_flag), версія схеми.

3. Rules Engine: скоринг очок/ХР, перевірка місій/квестів, тригери нагород/повідомлень.

4. Reward Orchestrator: розрахунок нагороди, бюджет-чек, RG/KYC-гейти, створення «завдання видачі», запис в журнал.

5. Payout/Bonus Service: кеш/бонус-кеш/фріспіни/купони, зовнішні вебхуки (гаманець, провайдери).

6. Notifier: push/in-app/email/месенджери з частотними лімітами.

7. Storage/Analytics: сирі події, вітрини, A/B, алерти.

8. Anti-Fraud/RG: капи, евристики/ML, hold-and-review великих призів.

2) Модель подій (мінімальний набір)

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) Рушій правил: Як описати логіку

Концепції: правила (if/then), сегменти, вікна часу, капи, пріоритети, версіонування.

Приклад декларативного правила (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) Вебхукі: сервер інтеграції

4. 1. Вихідні вебхуки (від вас до провайдерів/гаманця)

Метод: `POST https://partner. example/payouts`

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

Ретраї: експоненціальний backoff,'max _ retries = 8', jitter, DLQ.

Idempotency: повтор той же'X-Request-Id'→ партнер зобов'язаний відповідати тим же'payout _ id/status'.

Приклад 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. Вхідні вебхуки (до вас)

Дозволяйте тільки списки IP/MTLS, перевіряйте HMAC і час життя підпису ('X-Timestamp', ± 5 хвилин).

Зберігайте «сирий» body + заголовки в аудит-сховищі (WORM).

Будь-який дубль/повтор → перевіряйте idempotency key проти журналу.

5) Надійність: «рівний» потік без подвійних виплат

At-least-once на ingest + idempotent обробники → золотий стандарт.

Idempotency key: 'hash (event_id + user_id + rule_id)'для нарахування очок; окремий ключ для видачі нагороди'reward _ task _ id'.

Exactly-once семантика реалістична тільки логічно (через ідемпотентність), а не транспортом.

Порядок подій: зберігайте'event _ ts'і'ingest _ ts'; застосовуйте reordering window (наприклад, 60 сек) і replay з черги за ключем'user _ id'.

Dead Letter Queue (DLQ):

Пишемо туди повідомлення з перманентною помилкою (тимчасова схема не пройшла, підпис невалідний, бюджет закритий).
Сервіс «рев'ю DLQ» з кнопками reprocess/drop/fix schema.

6) Бюджети і захист маржі

Пули бюджетів: `nov_season`, `daily_sprint`, `vip_weekend`.

Квоти: soft/hard cap, «circuit breaker» - при досягненні 90% бюджету переводити великі призи в hold-state.

Єдина вартість: `Prize & Bonus Cost per Active/Payor`, Net Uplift.

Пріоритети: RG і комплаєнс важливіше промо - при конфлікті нагорода відкладається.

Приклад перевірки бюджету (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-гейти (безпека гравця і комплаєнс)

KYC: мінімум L2 для кешу/великих призів; фриспіни допустимі з L1.

RG: перевірка лімітів депозитів, самовиключення, «cool-off» → нагороди «заморожуються» до зняття обмежень.

Geo: список дозволених країн для кожного правила/пулу нагород.

Порогові алерти: різке зростання «майже-досяг» у окремих акаунтів = привід на hold & review.

8) Антифрод-правила і телеметрія

Капи окулярів за ставкою/хв/год/добу, мінімальна дисперсія ставок, заборона «ідеальних» патернів.

Техсигнали: headless, повторювані device_fp, проксі-субмережі.

Аномалії: «очок/ставок» і «очок/хв» - довгі «хвости» на 99-перцентиле.

Hold-and-review для топ-призерів: автоматичний чек KYC + ручний перегляд.

9) Моніторинг, метрики та алерти

SLO/SLA:

Ingest p95 ≤ 250 мс; обробка правила p95 ≤ 150 мс; оновлення лідерборда ≤ 2 с; видача нагороди ≤ 60 с.
Error budget < 0. 1% подій/добу.

Алерти:

SRM на експериментах (перекіс трафіку), зростання DLQ, падіння підпису HMAC-валідації, перевищення бюджету, сплеск idempotent-дублів.

Дашборд (щодня):

Події/с, лаг, відмовостійкість;
Воронка: подія правило ;
Вартість: Prize/Bonus per Active, Net Uplift;
Якість: фрод-прапори, KYC-блоки, RG-спрацьовування.

10) Версіонування та міграції

Кожне правило - versioned ('rules. version`).

Не можна редагувати активне правило без нової версії; використовуйте фічефлаг і «плавний прогрів» (10% → 50% → 100%).

Схема подій через schema registry; несумісні зміни - тільки major-версія.

11) A/B-тести автоматизації (коротко)

Одиниця - користувач; sticky-assignment; стратифікація (payer/geo/platform).

Роздільні лідерборди або нормалізація очок, щоб виключити інтерференцію.

Primary: participation_net, completion, Net ARPPU; Guardrails: скарги/1k, фрод-прапори, RG-спрацьовування.

CUPED і коваріати для зниження дисперсії.

12) Приклади: від правила до видачі

12. 1. Тригер «мікро-нагорода за прогрес»

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. Вихідний вебхук на гаманець


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

Успіх →'reward _ task'='succeeded'і запис в'reward _ ledger'.

Провал (5хх/таймаут) → ретрай з тим же'X-Request-Id'.

Провал (4xx) → DLQ + ручний розбір.

13) Сховища та таблиці (скетч)

sql
-- журнал нагород
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
);

-- індемпотентність
CREATE UNIQUE INDEX uniq_reward_task ON reward_ledger (reward_task_id);

-- бюджет
CREATE TABLE reward_budget (
pool_id TEXT PRIMARY KEY,  budget NUMERIC(18,2),  spent NUMERIC(18,2),  period DATE
);

14) Безпека і приватність

HMAC-підписи, MTLS, allow-list IP.

Шифрування в транзиті/спокої, ротація ключів, секрети в vault.

Мінімізація даних в payload (PII окремо, за посиланням-токеном, TTL).

Аудит-логи незмінні (WORM).

Політика зберігання і видалення (право на забуття, дедупlication-safe).

15) Чек-лист запуску

Схеми подій і registry, контракти вебхуків (сигнатури, TTL).
Черги, ретраї, DLQ, ідемпотентні обробники.
Капи/гвардrail-и в правилах, KYC/RG-гейти.
Бюджет-пули, circuit-breakers, алерти переповнення.
Дашборди SLO + воронка reward.
A/B-фічефлаги і SRM-моніторинг.
Runbook інцидентів (перегравання, заморожування, ручна видача).

16) Міні-кейс (синтетичний)

Підключені події з провайдерів ігор і гаманця; включений «win/bet» скоринг з капами.

Вебхуки підписані HMAC, ретраї до 8 спроб, DLQ з рев'ю кожні 2 год.

За 4 тижні: лаг обробки p95 180 мс; DLQ < 0,06%; дублі виплат 0; фрод-прапори −0,4 п.п.; ΔParticipation_net +6,3 п.п.; ΔARPPU (net) +€2,1 при Prize&Bonus/Active +€0,7.

Висновок: масштабування правил на нові гео з локальними бюджет-пулами.

Автоматизація нагород - це не «відправити пуш з фріспінами». Це інженерна система: надійна доставка подій, суворе версіонування правил, idempotency і підписи, бюджет-капери, KYC/RG-гейти, антифрод і моніторинг. Побудуйте цей каркас одного разу - і будь-які місії, турніри і «лут-моменти» будуть працювати передбачувано, вчасно і з позитивним нетто-ефектом.