# Oy ödülleri {#vote-rewards}

Oy ödülleri `server.vote` ve `project.vote` Webhook olaylarını kullanır: handler olayı alır, API ile oy verisini çeker ve ödülü yalnızca bir kez verir.

Önce [proje Webhook’unu](https://gamemonitoring.tr/developers/docs/webhook#connect) ve [signature](https://gamemonitoring.tr/developers/docs/webhook#signature) doğrulamasını ayarlayın. Oy verisi [GET /votes/:vote_id](https://gamemonitoring.tr/developers/docs/api/votes/:vote_id/__GET) ile istenir.

## Akış nasıl çalışır {#flow}

1. Webhook olayını alın ve [signature](https://gamemonitoring.tr/developers/docs/webhook#signature) doğrulayın. [is_test](https://gamemonitoring.tr/developers/docs/webhook#tests-resend) `true` ise oyu çekmeden ve ödül vermeden `204` döndürün.
2. `event_type` değerinin `server.vote` veya `project.vote` olduğundan emin olun.
3. `event_id` değerini oy ID’si olarak kullanın.
4. [GET /votes/:vote_id](https://gamemonitoring.tr/developers/docs/api/votes/:vote_id/__GET) ile oy verisini alın ve oyuncuyu kendi sisteminizde bulun.
5. Tek transaction içinde `event_type` + `event_id` ile [tekrar işleme korumasını](https://gamemonitoring.tr/developers/docs/webhook#deduplication) uygulayın ve ödülü yalnızca yeni olay için verin.
6. Ödül güvenli şekilde verilemiyorsa hata yanıtı döndürün. Sebep düzeltildikten sonra teslimatı arayüzden [tekrar gönderin](https://gamemonitoring.tr/developers/docs/webhook#tests-resend).

## Ödül örneği {#reward-example}

`PlayerName` oyuncusunun ID’si `1` olan server için oy verdiğini ve sisteminizin ona `100` coin eklemesi gerektiğini varsayalım.

1. GAMEMONITORING `event_type: server.vote` ve `event_id: 9824cabb-2203-437e-9b6c-aba43dde3e4b` ile Webhook gönderir.
2. Handler [signature](https://gamemonitoring.tr/developers/docs/webhook#signature) doğrular. İmza geçersizse `401` döndürür ve durur.
3. Handler `GET /votes/9824cabb-2203-437e-9b6c-aba43dde3e4b` ister, nickname, server ve user verisini alır, ardından yerel hesabı bulur.
4. Transaction içinde handler `event_type` + `event_id` değerini [tekrar işleme koruması](https://gamemonitoring.tr/developers/docs/webhook#deduplication) için kaydeder.
5. Yeni olay için handler aynı transaction içinde `100` coin ekler.
6. Tekrar teslimatta handler zaten kaydedilmiş olayı bulur, ödülü tekrar vermez ve `204` döndürür.

Aynı akış eşya, rol, VIP süresi, promosyon kodu veya dahili kuyruğa eklenecek işler için de uygundur.

## Oy olayı {#vote-event}

Server oyu için GAMEMONITORING `server.vote`, proje oyu için `project.vote` olayını gönderir. Olay gövdesinde yalnızca teslimat verileri vardır: `event_type`, `event_id`, `is_test` ve `signature`. Tam oy verisi ayrıca istenmelidir.

**Olay örneği**

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

Bu olayda `event_id` oy ID’sidir. Nickname, server veya user verisi için Webhook gövdesini kaynak olarak kullanmayın: bu veriler API’den gelir.

## Oy verisini alma {#fetch-vote}

`event_id` değerini `vote_id` olarak kullanın ve oy verisini [GET /votes/:vote_id](https://gamemonitoring.tr/developers/docs/api/votes/:vote_id/__GET) ile isteyin:

**Oy verisi isteği**

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

Ödül vermek için genellikle `response.nickname`, `response.server` ve public `response.user` verileri gerekir. Ödül belirli bir server’a bağlıysa her zaman `response.server.id` kontrol edin.

Alanları kullanma şekli: `response.nickname` veritabanınızdaki oyuncu hesabını bulmaya yardım eder, `response.server.id` server için ödül kuralını seçer, `response.user.id` ise oy veren GAMEMONITORING kullanıcı ID’si olarak ödül loguna yazılabilir.

API geçici olarak kullanılamıyorsa veya beklenmeyen yanıt veriyorsa doğrulama yapmadan ödül vermeyin. Hata kodu döndürün, sebebi düzeltin ve teslimatı arayüzden [tekrar gönderin](https://gamemonitoring.tr/developers/docs/webhook#tests-resend).

## Adım 3. Oy ödülü handler’ı {#complete-example}

Örnek temel handler’ın devamıdır: imzayı doğrular, oy verisini alır, olayı tekrar işlemeye karşı korur ve ödülü tek transaction içinde ekler. Kullanıcı tablosu adını, bakiye alanını ve oyuncu arama kuralını kendi sistem yapınızla değiştirin.

Örneği çalıştırmadan önce [proje Webhook’unu](https://gamemonitoring.tr/developers/docs/webhook#connect) ayarlayın, [GET /votes/:vote_id](https://gamemonitoring.tr/developers/docs/api/votes/:vote_id/__GET) endpoint’ini kontrol edin ve SQL user update sorgularını kendi hesap modelinizle değiştirin.

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