Postback Guide

Reward your players automatically every time they vote for your server.

When a player votes for your server on SroForge, we send a signed HTTP request (a postback) to your server with the player's in-game identifier. Your server checks the signature and gives the reward. In your account this feature is called Vote rewards and the address that receives the requests is your callback URL.

How to turn on vote rewards

Your callback URL

The callback URL is the public address on your website that receives the postback. It must be reachable from the internet, and HTTPS is recommended.

Redirects are not followed, so use the final address (for example with or without www, exactly as your site answers).

Vote link (recommended)

Send logged-in players to your server page with their in-game identifier in the link:

https://sroforge.com/server/your-server-slug?user=PLAYER_ID

Set up your website

Pick the tab that matches your website. You only need to read that one.

SRO-CMS v2 - v3 by m1xawy

Written for the current version of m1xawy/sro-cms on GitHub. The postback route and its CSRF exception already exist in the CMS, so you only change the files below. All paths are relative to the root folder of your CMS.

Older copies of the CMS may use different helper names (for example Donate::DonateLog instead of Donate::log). If step 3 shows an error about an unknown method, compare it with the other postback... methods in your own VoteService.php.

Step 1. .env — add this line (you paste the real secret here in step 6):

SROFORGE_CALLBACK_SECRET=PASTE_YOUR_SECRET_HERE

Paste the secret exactly as shown: no quotes, no spaces, no < or > characters.

Step 2. config/vote.php — add this entry inside the array, before the last ];, and replace your-server-slug with yours:

    'sroforge' => [
        'enabled' => true, //Postback url: https://your-site.com/postback/sroforge
        'name' => 'SroForge',
        'route' => 'sroforge',
        'image' => 'https://sroforge.com/vote-button.png',
        'url' => 'https://sroforge.com/server/your-server-slug?user={JID}',
        'secret' => env('SROFORGE_CALLBACK_SECRET'),
        'ip' => '',
        'reward' => 5,
        'type' => 0,
        'timeout' => 12,
    ],

Step 3. app/Services/VoteService.php — paste this method inside the VoteService class, right before the last closing } of the file. The use lines it needs are already at the top of the file.

    public function postbackSroforge(Request $request)
    {
        $config = config("vote.sroforge");
        $remoteIp = $request->server('HTTP_CF_CONNECTING_IP') ?? $request->ip();

        $secret = $config['secret'] ?? null;
        if (!$secret) {
            // 5xx = SroForge retries later, so votes are not lost while the secret is being set up.
            Log::error("{$config['name']} secret is not configured");
            return response('Not configured', 503);
        }

        $body = $request->getContent();
        $timestamp = (string) $request->header('X-Toplist-Timestamp', '');
        $signature = (string) $request->header('X-Toplist-Signature', '');

        // 1. Reject old requests (replay protection, 5 minutes)
        if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
            Log::warning("Stale {$config['name']} postback", ['ip' => $remoteIp]);
            return response('Stale request', 400);
        }

        // 2. Verify the signature against the raw body
        $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
        if (!hash_equals($expected, $signature)) {
            Log::warning("Invalid {$config['name']} signature", ['ip' => $remoteIp]);
            return response('Invalid signature', 401);
        }

        $data = json_decode($body, true);
        if (!is_array($data)) {
            return response('Invalid payload', 400);
        }

        // 3. "Send test" button on SroForge: answer OK, no reward
        if (($data['event'] ?? '') === 'test') {
            return response('Test callback received', 200);
        }

        if (($data['event'] ?? '') !== 'vote') {
            return response('Ignored event', 200);
        }

        // 4. The JID comes from the vote link (?user={JID})
        $jid = (string) ($data['username'] ?? '');
        if ($jid === '' || !ctype_digit($jid)) {
            return response('Missing or invalid user ID', 200);
        }

        $user = User::where('jid', (int) $jid)->first();
        if (!$user) {
            return response('User not found', 200);
        }

        $now = Carbon::now();
        $timeout = $config['timeout'] ?? 12;
        $rewardAmount = $config['reward'] ?? 0;

        // 5. Cooldown per JID (also protects against paying twice on a SroForge retry)
        $voteLog = Vote::where('jid', $jid)->where('site', $config['route'])->first();
        if ($voteLog && $voteLog->expire && $now->lessThan(Carbon::parse($voteLog->expire))) {
            return response("Cooldown active until {$voteLog->expire}", 200);
        }

        DB::transaction(function () use ($user, $rewardAmount, $config, $jid, $now, $timeout) {
            TbUser::updateSilk($user->jid, $config['type'] ?? 0, $rewardAmount);

            Donate::log([
                'method' => "Vote [{$config['name']}]",
                'value' => $rewardAmount,
                'jid' => $user->jid,
            ]);

            // Only the expiry is updated: the player's own IP and fingerprint saved by the vote page stay intact.
            Vote::updateOrCreate(
                ['jid' => $jid, 'site' => $config['route']],
                ['expire' => $now->addHours($timeout)]
            );
        });

        return response('OK', 200);
    }

Step 4. app/Providers/SettingsServiceProvider.php — find the function applyVoteSettings and replace the whole function with this one:

    private function applyVoteSettings(array $settings): void
    {
        $vote = $this->decodeJson($settings['vote'] ?? null);

        if (empty($vote)) {
            return;
        }

        // Keep sites and keys from config/vote.php (like sroforge and its secret)
        // that are not saved in the admin settings yet.
        $vote = array_replace_recursive(config('vote', []), $vote);

        $hasEnabledSite = false;

        foreach ($vote as $site) {
            if (is_array($site) && ! empty($site['enabled'])) {
                $hasEnabledSite = true;
                break;
            }
        }

        Config::set('vote', $vote);

        Config::set('global.vote.enabled', $hasEnabledSite);
    }

Why this step matters: once you save the vote settings in the admin panel, the CMS reads the vote sites only from the database and ignores config/vote.php. Without this change, SroForge never appears and every postback is refused with Vote Site not found or disabled. If you update the CMS later (git pull), check that this change is still there.

Step 5. In the root folder of your CMS, run:

php artisan optimize:clear

Step 6. On SroForge, open the Vote rewards page of your server, enter https://your-site.com/postback/sroforge and save. Copy the secret, paste it in .env (step 1), run php artisan optimize:clear again and press Send test. The answer must be Test callback received.

Step 7. In your CMS admin panel, open the vote settings: SroForge is now in the list. Reward, silk type and timeout can be changed there. Players vote from the Vote page of your CMS, and their JID is added to the link automatically.

Plain PHP website (vSRO + SQL Server)

A ready-to-use postback.php for a standard vSRO database. It verifies the signature, makes sure every delivery is rewarded only once and adds silk to the account. Your vote link must send the account ID: https://sroforge.com/server/your-server-slug?user=JID

Requirements: the PHP sqlsrv extension. The tables TB_User and SK_Silk are the standard vSRO ones. If your database was modified, adapt the queries.

Step 1. Folder layout. Keep the secret in a file outside your public web folder, so nobody can open it in a browser:

your-site/
├─ private/
│  └─ sroforge.php     (secret and database login)
└─ public/              (your web root)
   └─ postback.php     (https://your-site.com/postback.php)

Step 2. private/sroforge.php — paste the secret exactly as shown: no quotes inside, no spaces, no < or > characters.

<?php
return [
    'secret'      => 'PASTE_YOUR_SECRET_HERE',
    'db_server'   => 'PASTE_SQL_SERVER_HOST',
    'db_user'     => 'PASTE_SQL_USER',
    'db_pass'     => 'PASTE_SQL_PASSWORD',
    'silk_reward' => 5,
];

Step 3. Create the delivery table once (run it in SQL Server Management Studio):

USE SRO_VT_ACCOUNT;

CREATE TABLE dbo._SroForgeDeliveries (
    DeliveryID varchar(36) NOT NULL PRIMARY KEY,
    JID        int         NOT NULL,
    RewardedAt datetime    NOT NULL DEFAULT GETDATE()
);

Step 4. public/postback.php

<?php
$config = require __DIR__ . '/../private/sroforge.php';

$body      = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TOPLIST_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_TOPLIST_SIGNATURE'] ?? '';

// 1. Reject old requests (replay protection)
if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
    http_response_code(400);
    exit('Stale request');
}

// 2. Verify the signature
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $config['secret']);
if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($body, true);
if (! is_array($data)) {
    http_response_code(400);
    exit('Invalid payload');
}

// 3. "Send test" button: answer OK, no reward
if (($data['event'] ?? '') === 'test') {
    exit('OK');
}
if (($data['event'] ?? '') !== 'vote') {
    exit('Ignored');
}

// 4. The vote link sends the JID in "username"
$deliveryId = (string) ($data['delivery_id'] ?? '');
$jid        = (string) ($data['username'] ?? '');
if ($deliveryId === '' || ! ctype_digit($jid)) {
    exit('Invalid user'); // 200 on purpose: retrying would not help
}

$conn = sqlsrv_connect($config['db_server'], [
    'Database'     => 'SRO_VT_ACCOUNT',
    'UID'          => $config['db_user'],
    'PWD'          => $config['db_pass'],
    'CharacterSet' => 'UTF-8',
]);
if ($conn === false) {
    http_response_code(503); // 5xx: SroForge tries again later
    exit('Database unavailable');
}

// 5. The account must exist
$user = sqlsrv_query($conn, 'SELECT JID FROM dbo.TB_User WHERE JID = ?', [(int) $jid]);
if ($user === false) {
    http_response_code(503);
    exit('Database error');
}
if (! sqlsrv_fetch($user)) {
    exit('User not found');
}

sqlsrv_begin_transaction($conn);

// 6. Remember the delivery. A repeated delivery_id breaks the primary key,
//    so the same vote can never be rewarded twice.
$saved = sqlsrv_query(
    $conn,
    'INSERT INTO dbo._SroForgeDeliveries (DeliveryID, JID) VALUES (?, ?)',
    [$deliveryId, (int) $jid]
);
if ($saved === false) {
    sqlsrv_rollback($conn);
    $errors = sqlsrv_errors() ?: [];
    if ((int) ($errors[0]['code'] ?? 0) === 2627) {
        exit('Already rewarded');
    }
    http_response_code(503);
    exit('Database error');
}

// 7. Add the silk
$reward  = (int) $config['silk_reward'];
$updated = sqlsrv_query(
    $conn,
    'UPDATE dbo.SK_Silk SET silk_own = silk_own + ? WHERE JID = ?',
    [$reward, (int) $jid]
);
if ($updated !== false && sqlsrv_rows_affected($updated) === 0) {
    // First silk for this account: create its row
    $updated = sqlsrv_query(
        $conn,
        'INSERT INTO dbo.SK_Silk (JID, silk_own, silk_gift, silk_point) VALUES (?, ?, 0, 0)',
        [(int) $jid, $reward]
    );
}
if ($updated === false) {
    sqlsrv_rollback($conn);
    http_response_code(503);
    exit('Database error');
}

sqlsrv_commit($conn);
echo 'OK';

Step 5. On SroForge, open the Vote rewards page, enter https://your-site.com/postback.php, save, paste the secret in private/sroforge.php and press Send test. The answer must be OK.

Custom website or another CMS

Your endpoint must do four things:

  • 1. Verify the signature against the raw request body (see Request). Answer 401 if it does not match.
  • 2. Answer 200 to event: "test" without giving a reward.
  • 3. Store the delivery_id and give the reward only once per delivery_id.
  • 4. Answer 2xx when the vote is handled. Answer 5xx only for temporary problems (for example the database is down), so we try again later.

Where to keep your secret

Never put the secret in a file that can be opened in a browser. Paste it exactly as shown: no quotes, no spaces, no < or > characters.

Laravel: add the secret to .env and read it through a config file:

// .env
SROFORGE_CALLBACK_SECRET=PASTE_YOUR_SECRET_HERE

// config/services.php, inside the returned array
'sroforge' => [
    'secret' => env('SROFORGE_CALLBACK_SECRET'),
],

// in your code
$secret = config('services.sroforge.secret');

After every change to .env, run php artisan config:clear.

Laravel: route and CSRF

Create a POST route and read the raw body with $request->getContent(). Exclude the route from CSRF protection, otherwise every postback is refused with HTTP 419.

// routes/web.php
Route::post('/postback/sroforge', [YourController::class, 'postbackSroforge']);

// Laravel 11 and newer: bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'postback/sroforge',
    ]);
})

// Laravel 10 and older: app/Http/Middleware/VerifyCsrfToken.php
protected $except = [
    'postback/sroforge',
];

Minimal example in PHP

<?php
$secret = 'YOUR_CALLBACK_SECRET';

$body      = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TOPLIST_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_TOPLIST_SIGNATURE'] ?? '';

// 1. Reject old requests (replay protection)
if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
    http_response_code(400);
    exit('Stale request');
}

// 2. Verify the signature
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($body, true);

// 3. Test requests must not give rewards
if (($data['event'] ?? '') === 'test') {
    exit('OK');
}

// 4. Give the reward only once per delivery_id
$deliveryId = $data['delivery_id'];
$username   = $data['username'];
// ... check $deliveryId in your database, then reward $username ...

http_response_code(200);
echo 'OK';

Request

We send an HTTP POST request with a JSON body to your callback URL. Your endpoint checks the signature, gives the reward and answers with any 2xx status.

Headers

Body

{
  "event": "vote",
  "delivery_id": "a97d48b9-5161-41cd-9f04-00c8d91fa085",
  "vote_id": 123,
  "server": "your-server-slug",
  "username": "PlayerName",
  "voted_at": "2026-09-21T12:32:06+00:00"
}

Retries

Good to know

Add your server