DocsPostback Security & HMAC Verification

Postback Security & HMAC Verification

Cryptographic authentication for server-to-server postbacks using HMAC-SHA256 signatures.

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}
  1. {click_id}: Your custom tracking click identifier passed on click/launch (e.g. affiliate_clk_999).
  2. {conversion_id}: Perkox unique numerical conversion ID (e.g. 10482).
  3. {payout}: Publisher payout amount in USD (e.g. 3.50).
  4. {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.