# Recompense pentru voturi {#vote-rewards}

Recompensele pentru voturi folosesc evenimentele Webhook `server.vote` și `project.vote`: handlerul primește evenimentul, obține datele votului prin API și acordă recompensa o singură dată.

Configurați mai întâi [Webhook-ul proiectului](https://gamemonitoring.ro/developers/docs/webhook#connect) și verificarea [signature](https://gamemonitoring.ro/developers/docs/webhook#signature). Datele votului sunt cerute prin [GET /votes/:vote_id](https://gamemonitoring.ro/developers/docs/api/votes/:vote_id/__GET).

## Cum funcționează scenariul {#flow}

1. Primiți evenimentul Webhook și verificați [signature](https://gamemonitoring.ro/developers/docs/webhook#signature). Dacă [is_test](https://gamemonitoring.ro/developers/docs/webhook#tests-resend) este `true`, returnați `204` fără să cereți votul și fără să acordați recompensa.
2. Asigurați-vă că `event_type` este `server.vote` sau `project.vote`.
3. Folosiți `event_id` ca ID al votului.
4. Obțineți datele votului prin [GET /votes/:vote_id](https://gamemonitoring.ro/developers/docs/api/votes/:vote_id/__GET) și găsiți jucătorul în sistemul dvs.
5. Într-o singură tranzacție, aplicați [protecția împotriva procesării repetate](https://gamemonitoring.ro/developers/docs/webhook#deduplication) după `event_type` + `event_id` și acordați recompensa doar pentru un eveniment nou.
6. Dacă recompensa nu poate fi acordată în siguranță, returnați un răspuns cu eroare. După remedierea cauzei, [trimiteți din nou livrarea](https://gamemonitoring.ro/developers/docs/webhook#tests-resend) din interfață.

## Exemplu de recompensă {#reward-example}

Să presupunem că jucătorul `PlayerName` a votat pentru serverul cu ID `1`, iar sistemul dvs. trebuie să îi adauge `100` monede.

1. GAMEMONITORING trimite un Webhook cu `event_type: server.vote` și `event_id: 9824cabb-2203-437e-9b6c-aba43dde3e4b`.
2. Handlerul verifică [signature](https://gamemonitoring.ro/developers/docs/webhook#signature). Dacă semnătura este invalidă, returnează `401` și se oprește.
3. Handlerul cere `GET /votes/9824cabb-2203-437e-9b6c-aba43dde3e4b`, primește nickname, server și utilizator, apoi găsește contul local.
4. Într-o tranzacție, handlerul salvează `event_type` + `event_id` pentru [protecția împotriva procesării repetate](https://gamemonitoring.ro/developers/docs/webhook#deduplication).
5. Pentru un eveniment nou, handlerul adaugă `100` monede în aceeași tranzacție.
6. La o livrare repetată, handlerul găsește evenimentul deja salvat, nu acordă recompensa din nou și returnează `204`.

Același scenariu este potrivit și pentru obiecte, roluri, timp VIP, coduri promoționale sau sarcini într-o coadă internă.

## Evenimentul de vot {#vote-event}

Pentru un vot de server, GAMEMONITORING trimite `server.vote`, iar pentru un vot de proiect — `project.vote`. Body-ul evenimentului conține doar date de livrare: `event_type`, `event_id`, `is_test` și `signature`. Datele complete ale votului trebuie cerute separat.

**Exemplu de eveniment**

```json
{
  "event_id": "9824cabb-2203-437e-9b6c-aba43dde3e4b",
  "event_type": "server.vote",
  "is_test": false,
  "signature": "ae83b8aba88a3a9ab3b97b1f6d65664da5628a9cb64d56d5132807bca5472e4f"
}
```

În acest eveniment, `event_id` este ID-ul votului. Nu folosiți body-ul Webhook ca sursă pentru nickname, server sau utilizator: aceste date vin din API.

## Obținerea datelor votului {#fetch-vote}

Folosiți `event_id` ca `vote_id` și cereți datele votului prin [GET /votes/:vote_id](https://gamemonitoring.ro/developers/docs/api/votes/:vote_id/__GET):

**Cerere pentru datele votului**

```bash
curl -sS "https://api.gamemonitoring.ro/votes/9824cabb-2203-437e-9b6c-aba43dde3e4b"
```

Pentru acordarea recompensei, de obicei aveți nevoie de `response.nickname`, `response.server` și datele publice `response.user`. Dacă recompensa depinde de un anumit server, verificați întotdeauna `response.server.id`.

Cum se folosesc câmpurile: `response.nickname` ajută la găsirea contului jucătorului în baza dvs., `response.server.id` alege regula de recompensă pentru server, iar `response.user.id` poate fi salvat în logul recompenselor ca ID al utilizatorului GAMEMONITORING care a votat.

Dacă API-ul este temporar indisponibil sau returnează un răspuns neașteptat, nu acordați recompensa fără verificare. Returnați un cod de eroare, remediați cauza și [trimiteți din nou livrarea](https://gamemonitoring.ro/developers/docs/webhook#tests-resend) din interfață.

## Pasul 3. Handler pentru recompensa după vot {#complete-example}

Exemplul continuă handlerul de bază: verifică semnătura, obține datele votului, protejează evenimentul de procesare repetată și acordă recompensa într-o singură tranzacție. Înlocuiți numele tabelului de utilizatori, câmpul de balanță și regula de căutare a jucătorului cu structura sistemului dvs.

Înainte de rularea exemplului, configurați [Webhook-ul proiectului](https://gamemonitoring.ro/developers/docs/webhook#connect), verificați [GET /votes/:vote_id](https://gamemonitoring.ro/developers/docs/api/votes/:vote_id/__GET) și înlocuiți actualizările SQL pentru utilizator cu modelul dvs. de conturi.

### PHP

```php
<?php
// Replace this token with the signing token from your GAMEMONITORING webhook settings.
$secret = 'paste-webhook-token-here';

// Add the GAMEMONITORING API URL and reward settings for vote events.
$apiUrl = 'https://api.gamemonitoring.ro';
$rewardAmount = '1.00';

// Read and decode the JSON body sent by GAMEMONITORING.
$event = json_decode(file_get_contents('php://input'), true) ?: [];

// Test deliveries are signed too. Normalize the boolean value to the lowercase
// string used by GAMEMONITORING when the signature is calculated.
$isTest = ($event['is_test'] ?? false) === true;
$signingData = array_replace($event, ['is_test' => $isTest ? 'true' : 'false']);

// Build the exact signing string: all body fields except signature,
// sorted by key and joined as key=value pairs with &.
$fields = array_values(array_filter(array_keys($event), fn($field) => $field !== 'signature'));
sort($fields, SORT_STRING);

// Calculate HMAC-SHA256 with the webhook token from your settings.
$signing = implode('&', array_map(fn($field) => $field . '=' . (string) ($signingData[$field] ?? ''), $fields));
$expected = hash_hmac('sha256', $signing, $secret);
$actual = (string) ($event['signature'] ?? '');

// Reject the request before doing any work when the signature is invalid.
if (!hash_equals($expected, $actual)) {
    http_response_code(401);
    exit;
}

// Test deliveries must not change balance, inventory, roles, or production data.
if ($isTest) {
    http_response_code(204);
    exit;
}

// Real deliveries must include an event type and a stable event id.
$eventType = (string) ($event['event_type'] ?? '');
$eventId = (string) ($event['event_id'] ?? '');

if ($eventType === '' || $eventId === '') {
    http_response_code(400);
    exit;
}

// This reward handler processes server and project vote events.
if (!in_array($eventType, ['server.vote', 'project.vote'], true)) {
    http_response_code(204);
    exit;
}

// At this point the webhook is trusted. Load vote data before opening a database transaction.
$pdo = null;

try {
    // Load full vote data by event_id. Nickname, entity, and user data are not
    // in the webhook body. Return 500 if the API cannot confirm the vote.
    $voteUrl = $apiUrl . '/votes/' . rawurlencode($eventId);
    $voteContext = stream_context_create(['http' => ['timeout' => 5]]);
    $voteBody = @file_get_contents($voteUrl, false, $voteContext);

    if ($voteBody === false) {
        throw new RuntimeException('Vote API request failed');
    }

    $voteResponse = json_decode($voteBody, true) ?: [];
    $vote = $voteResponse['response'] ?? null;

    // Do not issue a reward when the vote response is missing a concrete nickname.
    if (!is_array($vote) || !isset($vote['nickname']) || !is_string($vote['nickname'])) {
        throw new RuntimeException('Vote API response does not include nickname');
    }

    // Verify that the API entity matches the event before changing the account.
    $expectedEntityType = $eventType === 'project.vote' ? 'project' : 'server';
    if (($vote['entity_type'] ?? '') !== $expectedEntityType) {
        throw new RuntimeException('Vote entity type does not match event type');
    }

    // Use vote nickname to update the local account. The entity id is available in
    // vote.entity_id and in either vote.server.id or vote.project.id.
    $nickname = trim($vote['nickname']);

    if ($nickname === '') {
        throw new RuntimeException('Vote nickname is empty');
    }

    // Add your local database connection for deduplication and event-specific work.
    $pdo = new PDO('mysql:host=127.0.0.1;dbname=game;charset=utf8mb4', 'game', 'password', [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    ]);

    // Keep deduplication and the real state change in one transaction.
    // If any step fails, return 500 so the delivery can be retried.
    $pdo->beginTransaction();

    // Store the event once. This requires the table to have a unique key on
    // (event_type, event_id). Duplicate deliveries affect zero rows.
    $deduplicate = $pdo->prepare('INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)');
    $deduplicate->execute([$eventType, $eventId]);

    // The event was already processed earlier. Return success without changing
    // state again, because duplicate delivery is expected.
    if ($deduplicate->rowCount() === 0) {
        $pdo->commit();
        http_response_code(204);
        exit;
    }

    // Add event-specific database changes here. Keep them after the
    // deduplication insert and inside this same transaction.
    $balance = $pdo->prepare('UPDATE users SET balance = balance + ? WHERE nickname = ?');
    $balance->execute([$rewardAmount, $nickname]);

    // Commit only after deduplication and event-specific work both succeed.
    $pdo->commit();

    // Log only newly processed real events after the transaction succeeds.
    syslog(LOG_INFO, 'Accepted webhook event ' . $eventType . ' #' . $eventId);

    http_response_code(204);
} catch (Throwable $error) {
    // Roll back partial database work so the event can be retried safely.
    if ($pdo instanceof PDO && $pdo->inTransaction()) {
        $pdo->rollBack();
    }

    // 500 keeps the delivery failed instead of marking unfinished work as done.
    http_response_code(500);
}
```

### JavaScript

```javascript
const crypto = require('node:crypto')
const express = require('express')
const mysql = require('mysql2/promise')

const app = express()
// Replace this token with the signing token from your GAMEMONITORING webhook settings.
const secret = 'paste-webhook-token-here'

// Add the GAMEMONITORING API URL and reward settings for vote events.
const apiUrl = 'https://api.gamemonitoring.ro'
const rewardAmount = '1.00'

// Add your local database connection for deduplication and event-specific work.
const db = mysql.createPool({
  database: 'game',
  host: '127.0.0.1',
  password: 'password',
  user: 'game',
})

// GAMEMONITORING sends JSON with Content-Type: application/json.
app.use(express.json())

function isValidSignature(event) {
  // Build the exact signing string: all body fields except signature,
  // sorted by key and joined as key=value pairs with &.
  const fields = Object.keys(event).filter((field) => field !== 'signature').sort()
  const signing = fields.map((field) => field + '=' + String(event[field] ?? '')).join('&')

  // Calculate HMAC-SHA256 with the webhook token from your settings.
  const expected = crypto.createHmac('sha256', secret).update(signing).digest('hex')
  const actual = String(event.signature || '')

  // timingSafeEqual requires buffers with the same length.
  const expectedBuffer = Buffer.from(expected)
  const actualBuffer = Buffer.from(actual)

  return expectedBuffer.length === actualBuffer.length && crypto.timingSafeEqual(expectedBuffer, actualBuffer)
}

app.post('/gamemonitoring-webhook', async (req, res) => {
  // Read the webhook payload parsed by express.json().
  const event = req.body || {}

  // Reject the request before doing any work when the signature is invalid.
  if (!isValidSignature(event)) {
    return res.sendStatus(401)
  }

  // Test deliveries must not change balance, inventory, roles, or production data.
  if (event.is_test === true) {
    return res.sendStatus(204)
  }

  // Real deliveries must include an event type and a stable event id.
  const eventType = String(event.event_type || '')
  const eventId = String(event.event_id || '')

  if (!eventType || !eventId) {
    return res.sendStatus(400)
  }

  // This reward handler processes server and project vote events.
  if (!['server.vote', 'project.vote'].includes(eventType)) {
    return res.sendStatus(204)
  }

  // At this point the webhook is trusted. Load vote data before opening a database transaction.
  let connection

  try {
    // Load full vote data by event_id. Nickname, entity, and user data are not
    // in the webhook body. Return 500 if the API cannot confirm the vote.
    const voteUrl = apiUrl + '/votes/' + encodeURIComponent(eventId)
    const voteResponse = await fetch(voteUrl, { signal: AbortSignal.timeout(5000) })

    if (!voteResponse.ok) {
      throw new Error('Vote API request failed')
    }

    const voteBody = await voteResponse.json()
    const vote = voteBody.response

    // Do not issue a reward when the vote response is missing a concrete nickname.
    if (!vote || typeof vote.nickname !== 'string') {
      throw new Error('Vote API response does not include nickname')
    }

    // Verify that the API entity matches the event before changing the account.
    const expectedEntityType = eventType === 'project.vote' ? 'project' : 'server'
    if (vote.entity_type !== expectedEntityType) {
      throw new Error('Vote entity type does not match event type')
    }

    // Use vote nickname to update the local account. The entity id is available in
    // vote.entity_id and in either vote.server.id or vote.project.id.
    const nickname = vote.nickname.trim()

    if (!nickname) {
      throw new Error('Vote nickname is empty')
    }

    connection = await db.getConnection()

    // Keep deduplication and the real state change in one transaction.
    // If any step fails, return 500 so the delivery can be retried.
    await connection.beginTransaction()

    // Store the event once. This requires the table to have a unique key on
    // (event_type, event_id). Duplicate deliveries affect zero rows.
    const [deduplicate] = await connection.execute(
      'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)',
      [eventType, eventId],
    )

    // The event was already processed earlier. Return success without changing
    // state again, because duplicate delivery is expected.
    if (deduplicate.affectedRows === 0) {
      await connection.commit()
      return res.sendStatus(204)
    }

    // Add event-specific database changes here. Keep them after the
    // deduplication insert and inside this same transaction.
    await connection.execute('UPDATE users SET balance = balance + ? WHERE nickname = ?', [rewardAmount, nickname])

    // Commit only after deduplication and event-specific work both succeed.
    await connection.commit()

    // Log only newly processed real events after the transaction succeeds.
    console.log('Accepted webhook event ' + eventType + ' #' + eventId)

    return res.sendStatus(204)
  } catch (error) {
    // Roll back partial database work so the event can be retried safely.
    if (connection) {
      await connection.rollback()
    }

    // 500 keeps the delivery failed instead of marking unfinished work as done.
    return res.sendStatus(500)
  } finally {
    // Return the connection to the pool.
    if (connection) {
      connection.release()
    }
  }
})

app.listen(3000)
```

### Python

```python
import hashlib
import hmac

import pymysql
import requests
from flask import Flask, abort, request

app = Flask(__name__)
# Replace this token with the signing token from your GAMEMONITORING webhook settings.
secret = b'paste-webhook-token-here'

# Add the GAMEMONITORING API URL and reward settings for vote events.
api_url = 'https://api.gamemonitoring.ro'
reward_amount = '1.00'

# Add your local database connection for deduplication and event-specific work.
db_config = {
    'database': 'game',
    'host': '127.0.0.1',
    'password': 'password',
    'user': 'game',
}

def stringify(value):
    # GAMEMONITORING signs booleans as lowercase true/false strings.
    if isinstance(value, bool):
        return 'true' if value else 'false'

    return '' if value is None else str(value)

def is_valid_signature(event):
    # Build the exact signing string: all body fields except signature,
    # sorted by key and joined as key=value pairs with &.
    fields = sorted(field for field in event.keys() if field != 'signature')
    signing = '&'.join(f'{field}={stringify(event.get(field))}' for field in fields)

    # Calculate HMAC-SHA256 with the webhook token from your settings.
    expected = hmac.new(secret, signing.encode(), hashlib.sha256).hexdigest()
    actual = str(event.get('signature') or '')

    return hmac.compare_digest(expected, actual)

@app.post('/gamemonitoring-webhook')
def gamemonitoring_webhook():
    # Read and decode the JSON body sent by GAMEMONITORING.
    event = request.get_json(silent=True) or {}

    # Reject the request before doing any work when the signature is invalid.
    if not is_valid_signature(event):
        abort(401)

    # Test deliveries must not change balance, inventory, roles, or production data.
    if event.get('is_test') is True:
        return '', 204

    # Real deliveries must include an event type and a stable event id.
    event_type = str(event.get('event_type') or '')
    event_id = str(event.get('event_id') or '')

    if not event_type or not event_id:
        abort(400)

    # This reward handler processes server and project vote events.
    if event_type not in ('server.vote', 'project.vote'):
        return '', 204

    # At this point the webhook is trusted. Load vote data before opening a database transaction.
    connection = None

    try:
        # Load full vote data by event_id. Nickname, entity, and user data
        # are not in the webhook body. Return 500 if the API cannot confirm the vote.
        vote_url = f"{api_url}/votes/{event_id}"
        response = requests.get(vote_url, timeout=5)

        if not response.ok:
            raise RuntimeError('Vote API request failed')

        vote = response.json().get('response')

        # Do not issue a reward when the vote response is missing a concrete nickname.
        if not isinstance(vote, dict) or not isinstance(vote.get('nickname'), str):
            raise RuntimeError('Vote API response does not include nickname')

        # Verify that the API entity matches the event before changing the account.
        expected_entity_type = 'project' if event_type == 'project.vote' else 'server'
        if vote.get('entity_type') != expected_entity_type:
            raise RuntimeError('Vote entity type does not match event type')

        # Use vote nickname to update the local account. The entity id is available in
        # vote.entity_id and in either vote.server.id or vote.project.id.
        nickname = vote['nickname'].strip()

        if not nickname:
            raise RuntimeError('Vote nickname is empty')

        connection = pymysql.connect(**db_config)
        connection.begin()

        # Keep deduplication and the real state change in one transaction.
        # If any step fails, return 500 so the delivery can be retried.
        with connection.cursor() as cursor:
            # Store the event once. This requires the table to have a unique key
            # on (event_type, event_id). Duplicate deliveries affect zero rows.
            cursor.execute(
                'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (%s, %s)',
                (event_type, event_id),
            )

            # The event was already processed earlier. Return success without
            # changing state again, because duplicate delivery is expected.
            if cursor.rowcount == 0:
                connection.commit()
                return '', 204

            # Add event-specific database changes here. Keep them after the
            # deduplication insert and inside this same transaction.
            cursor.execute('UPDATE users SET balance = balance + %s WHERE nickname = %s', (reward_amount, nickname))

        # Commit only after deduplication and event-specific work both succeed.
        connection.commit()

        # Log only newly processed real events after the transaction succeeds.
        app.logger.info('Accepted webhook event %s #%s', event_type, event_id)

        return '', 204
    except Exception:
        # Roll back partial database work so the event can be retried safely.
        if connection:
            connection.rollback()

        # 500 keeps the delivery failed instead of marking unfinished work as done.
        abort(500)
    finally:
        # Close the database connection.
        if connection:
            connection.close()
```
