Why Postback Security is Mandatory
Without cryptographic authentication, malicious actors could guess your postback endpoint URL and send fake conversion requests to credit themselves unlimited in-game currency.
Perkox signs every postback request using an HMAC-SHA256 signature generated with your private Postback Secret Key. Because only your server and Perkox know this key, forged requests are detected and rejected instantly.
Live Postback HMAC-SHA256 Signature Tester
Canonical format: {click_id}|{conversion_id}|{payout}|{status}
CANONICAL PAYLOAD STRING (PIPE-DELIMITED){click_id}|{conversion_id}|{payout}|{status}
—
CALCULATED HMAC-SHA256 SIGNATURESHA-256 (64 hex characters)
Enter a secret key above to generate signature
FULL TEST POSTBACK URL
https://api.yourdomain.com/postback?click_id=affiliate_clk_999&conversion_id=10482&payout=3.50&status=approved&player_id=player_1092&reward_amount=350.00&signature=
The Canonical Signature Specification
Perkox computes the HMAC-SHA256 signature over a pipe-delimited (|) concatenation of four standard parameters in exact sequence:
{click_id}|{conversion_id}|{payout}|{status}
- {click_id}: Your custom tracking click identifier passed on click/launch (e.g.
affiliate_clk_999). - {conversion_id}: Perkox unique numerical conversion ID (e.g.
10482). - {payout}: Publisher payout amount in USD (e.g.
3.50). - {status}: Conversion status string (e.g.
approved).
Server-Side Verification Code Examples
<?php
// Laravel Controller: app/Http/Controllers/PerkoxPostbackController.php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
class PerkoxPostbackController extends Controller
{
public function handle(Request $request)
{
$secretKey = env('PERKOX_POSTBACK_SECRET_KEY');
$receivedSignature = $request->query('signature') ?? $request->query('sig');
if (!$receivedSignature) {
return response('Missing signature', 400);
}
// 1. Extract the canonical signed fields
$clickId = (string) $request->query('click_id', '');
$conversionId = (string) $request->query('conversion_id', '');
$payout = (string) $request->query('payout', '');
$status = (string) $request->query('status', '');
// 2. Build canonical pipe-delimited payload
// Format: {click_id}|{conversion_id}|{payout}|{status}
$canonicalPayload = implode('|', [$clickId, $conversionId, $payout, $status]);
// 3. Compute HMAC-SHA256 signature
$expectedSignature = hash_hmac('sha256', $canonicalPayload, $secretKey);
// 4. Constant-time comparison to prevent timing attacks
if (!hash_equals($expectedSignature, $receivedSignature)) {
Log::warning('Invalid Perkox postback signature', [
'received' => $receivedSignature,
'expected' => $expectedSignature,
'payload' => $canonicalPayload
]);
return response('Invalid signature', 403);
}
// 5. Verify status and process reward idempotently
if ($status !== 'approved') {
return response('Postback acknowledged, no reward due', 200);
}
$playerId = $request->query('player_id');
$rewardAmount = (float) $request->query('reward_amount');
// Credit user balance in your database...
return response('OK', 200);
}
}Idempotency Protection
Network hiccups or timeouts can occasionally trigger automatic webhook retries. Always store processed
click_ids or conversion_ids in a database with a unique constraint so duplicate requests are ignored and users are never double-credited.
