# Nagrody za głosy {#vote-rewards}

Nagrody za głosy używają zdarzeń Webhook `server.vote` i `project.vote`: handler odbiera zdarzenie, pobiera dane głosu przez API i wydaje nagrodę tylko jeden raz.

Najpierw skonfiguruj [Webhook projektu](https://gamemonitoring.pl/developers/docs/webhook#connect) i weryfikację [signature](https://gamemonitoring.pl/developers/docs/webhook#signature). Dane głosu są pobierane przez [GET /votes/:vote_id](https://gamemonitoring.pl/developers/docs/api/votes/:vote_id/__GET).

## Jak działa scenariusz {#flow}

1. Przyjmij zdarzenie Webhook i sprawdź [signature](https://gamemonitoring.pl/developers/docs/webhook#signature). Jeśli [is_test](https://gamemonitoring.pl/developers/docs/webhook#tests-resend) ma wartość `true`, zwróć `204` bez pobierania głosu i bez wydawania nagrody.
2. Upewnij się, że `event_type` to `server.vote` lub `project.vote`.
3. Użyj `event_id` jako ID głosu.
4. Pobierz dane głosu przez [GET /votes/:vote_id](https://gamemonitoring.pl/developers/docs/api/votes/:vote_id/__GET) i znajdź gracza w swoim systemie.
5. W jednej transakcji zastosuj [ochronę przed ponownym przetworzeniem](https://gamemonitoring.pl/developers/docs/webhook#deduplication) po `event_type` + `event_id` i wydaj nagrodę tylko dla nowego zdarzenia.
6. Jeśli nagrody nie da się bezpiecznie wydać, zwróć odpowiedź z błędem. Po usunięciu przyczyny [ponów dostawę](https://gamemonitoring.pl/developers/docs/webhook#tests-resend) z interfejsu.

## Przykład nagrody {#reward-example}

Załóżmy, że gracz `PlayerName` zagłosował na serwer o ID `1`, a Twój system ma dodać mu `100` monet.

1. GAMEMONITORING wysyła Webhook z `event_type: server.vote` i `event_id: 9824cabb-2203-437e-9b6c-aba43dde3e4b`.
2. Handler sprawdza [signature](https://gamemonitoring.pl/developers/docs/webhook#signature). Jeśli podpis jest błędny, zwraca `401` i kończy.
3. Handler wywołuje `GET /votes/9824cabb-2203-437e-9b6c-aba43dde3e4b`, otrzymuje nick, serwer oraz użytkownika i znajduje lokalne konto.
4. W transakcji handler zapisuje `event_type` + `event_id` dla [ochrony przed ponownym przetworzeniem](https://gamemonitoring.pl/developers/docs/webhook#deduplication).
5. Dla nowego zdarzenia handler dodaje `100` monet w tej samej transakcji.
6. Przy ponownej dostawie handler znajduje już zapisane zdarzenie, nie wydaje nagrody drugi raz i zwraca `204`.

Ten sam scenariusz pasuje też do przedmiotów, ról, czasu VIP, kodów promocyjnych lub zadań w wewnętrznej kolejce.

## Zdarzenie głosu {#vote-event}

Dla głosu na serwer GAMEMONITORING wysyła `server.vote`, a dla głosu na projekt — `project.vote`. Body zdarzenia zawiera tylko dane dostawy: `event_type`, `event_id`, `is_test` i `signature`. Pełne dane głosu trzeba pobrać osobno.

**Przykład zdarzenia**

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

`event_id` w tym zdarzeniu jest ID głosu. Nie używaj body Webhook jako źródła nicku, serwera lub użytkownika: te dane pochodzą z API.

## Pobieranie danych głosu {#fetch-vote}

Użyj `event_id` jako `vote_id` i pobierz dane głosu przez [GET /votes/:vote_id](https://gamemonitoring.pl/developers/docs/api/votes/:vote_id/__GET):

**Żądanie danych głosu**

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

Do wydania nagrody zwykle potrzebujesz `response.nickname`, `response.server` i publicznych danych `response.user`. Jeśli nagroda zależy od konkretnego serwera, zawsze sprawdzaj `response.server.id`.

Jak używać pól: `response.nickname` pomaga znaleźć konto gracza w Twojej bazie, `response.server.id` wybiera regułę nagrody dla serwera, a `response.user.id` można zapisać w logu nagród jako ID użytkownika GAMEMONITORING, który oddał głos.

Jeśli API jest chwilowo niedostępne albo zwraca nieoczekiwaną odpowiedź, nie wydawaj nagrody bez weryfikacji. Zwróć kod błędu, napraw przyczynę i [ponów dostawę](https://gamemonitoring.pl/developers/docs/webhook#tests-resend) z interfejsu.

## Krok 3. Handler nagrody za głos {#complete-example}

Przykład kontynuuje podstawowy handler: sprawdza podpis, pobiera dane głosu, chroni zdarzenie przed ponownym przetworzeniem i dodaje nagrodę w jednej transakcji. Nazwę tabeli użytkowników, pole salda i regułę wyszukiwania gracza zastąp strukturą swojego systemu.

Przed uruchomieniem przykładu skonfiguruj [Webhook projektu](https://gamemonitoring.pl/developers/docs/webhook#connect), sprawdź [GET /votes/:vote_id](https://gamemonitoring.pl/developers/docs/api/votes/:vote_id/__GET) i zastąp SQL aktualizacji użytkownika swoim modelem kont.

### 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.pl';
$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.pl'
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.pl'
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()
```
