Placeholders Glossary
Placeholders enclosed in curly braces {...} are dynamically substituted by Perkox with live conversion values before the webhook is fired.
| Macro | Requirement | Description | Sample Output |
|---|---|---|---|
| {player_id} | Yes | Your user's unique identifier passed when opening the offerwall. | user_98214 |
| {reward_amount} | Yes | Amount of virtual currency to credit your user based on your exchange rate. | 150.00 |
| {payout} | Recommended | Publisher revenue earned in USD for this specific conversion. | 1.50 |
| {click_id} | Recommended | Your custom tracking click ID passed from client or generated by Perkox. Used for idempotency and signature. | clk_948f2a1b7e09 |
| {conversion_id} | Recommended | Perkox unique numerical conversion identifier. Included in canonical HMAC signature. | 10482 |
| {status} | Recommended | Conversion status: 'approved' (credit user) or 'chargeback' (revoke credit). Included in HMAC signature. | approved |
| {signature} | Recommended | Cryptographic HMAC-SHA256 signature calculated over {click_id}|{conversion_id}|{payout}|{status}. | 249e4f660e8f88... |
| {transaction_id} | Recommended | Internal unique conversion transaction identifier. | tx_8f3a92b1c4 |
| {offer_id} | Optional | ID of the completed offer in the Perkox catalog. | 5012 |
| {offer_name} | Optional | Name of the completed offer/campaign. | Hero Quest: Legends |
| {event} | Optional | Slug of the goal / tier achieved (e.g. 'install', 'reach_level_10'). | reach_level_10 |
| {event_name} | Optional | Human-readable label of the event. | Reach Level 10 |
| {ip} | Optional | IP address of the end user when completing the offer. | 192.168.1.1 |
| {country} | Optional | Two-letter ISO country code of the user. | US |
| {os_name} | Optional | Operating system name (e.g. 'Android', 'iOS', 'Windows'). | Android |
| {device_model} | Optional | Device model name reported by client/SDK. | Pixel 8 Pro |
| {sub1} - {sub10} | Optional | Custom pass-through sub-parameters provided by publisher during SDK launch. | placement_hero |
Accepted Aliases
If you are migrating from another network, Perkox automatically resolves common synonym spellings into our official macros:
| Your Macro | Resolved Perkox Token | Behavior |
|---|---|---|
| {user_id} | {player_id} | Standard synonym for player identifier |
| {reward} | {reward_amount} | Equivalent to reward amount in virtual currency |
| {click} / {clickid} | {click_id} | Alternative spellings of publisher click ID |
| {offerid} | {offer_id} | Direct alias for offer catalog ID |
| {offer} / {offername} | {offer_name} | Direct alias for campaign title |
| {txid} / {tx_id} / {transaction} | {transaction_id} | Conversion transaction ID aliases |
| {user_ip} / {ip_address} | {ip} | End-user IP address aliases |
| {os} | {os_name} | Operating system alias |
| {device} | {device_type} | Device type alias (mobile, tablet, desktop) |
Recommended Production Template
https://api.yourdomain.com/postback?user_id={player_id}&amount={reward_amount}&payout={payout}&click_id={click_id}&conversion_id={conversion_id}&status={status}&signature={signature}Handling Chargebacks
When
{status} returns chargeback, it indicates an advertiser reversed the transaction due to fraud, emulator usage, or cancelled subscriptions. Your system should deduce the corresponding virtual currency from the user balance.
