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
- 1. Create an account and add your server. New servers are reviewed before they appear in the ranking.
- 2. Prepare your website: open Set up your website below and pick the tab for your type of website.
- 3. In My servers, open the Vote rewards page of your server, enter your callback URL and save. A secret is generated and shown only once, so copy it right away and store it as your tab explains.
- 4. Press Send test. We send a request with
event: "test"and the usernameTestUser, so you can check your endpoint without a real vote. - 5. Add a vote link on your website or launcher (see below), so players never have to type anything.
- 6. Every delivery appears in the Delivery history on the Vote rewards page, where failed ones can be retried.
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.
- SRO-CMS (m1xawy):
https://your-site.com/postback/sroforge - Plain PHP website: the address of the file, for example
https://your-site.com/postback.php - Real example: VoidRoad uses
https://void-road.com/postback/sroforge
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
- Replace
your-server-slugwith the last part of your server page address on SroForge, andPLAYER_IDwith the value your server needs to give the reward: account ID (JID), account name or character name. You decide. - The value is sent back to you unchanged, in the
usernamefield of the postback. - With a valid
uservalue, the player only sees the captcha and the Vote button. There is nothing to type. - Allowed characters: letters, digits and underscore (
_), up to 64 characters. Other values are ignored and the player sees the normal form. - Players who open your server page without a vote link can still type their in-game name themselves. If a vote has no identifier at all, no postback is sent for it.
- The link is not secret: a player could change the value. The vote limit still applies (one vote per visitor every 12 hours), so this only changes who receives the reward, never how many votes are counted.
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
401if it does not match. - 2. Answer
200toevent: "test"without giving a reward. - 3. Store the
delivery_idand give the reward only once perdelivery_id. - 4. Answer
2xxwhen the vote is handled. Answer5xxonly 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
X-Toplist-Signature:sha256=followed by the HMAC-SHA256 oftimestamp + "." + raw body, using your secret as the key.X-Toplist-Timestamp: Unix time (seconds) when the request was signed.X-Toplist-Delivery: unique ID of the delivery. It is the same on every retry.X-Toplist-Event:votefor real votes,testfor the "Send test" button.
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
- Your endpoint has 10 seconds to answer.
- On a timeout, a connection error, a
5xx,408or429, we try again after 30 seconds, 2 minutes, 10 minutes, 30 minutes and 2 hours (6 attempts in total). - Other
4xxanswers and redirects (3xx) are not retried. The delivery is marked as failed and you can retry it from the Delivery history. - Every attempt is signed again with a fresh timestamp.
Good to know
- Always store the
delivery_id(or use a cooldown per player) so a retry can never give the reward twice. - Sign and compare against the raw request body, not a re-encoded copy of the JSON.
- Callback URLs that point to private, internal or reserved addresses are rejected.
- Keep your secret private. If it leaks, generate a new one on the Vote rewards page. The old one stops working immediately.