DocsPostback Macros & Dynamic Tokens

Postback Macros & Dynamic Tokens

Comprehensive glossary of dynamic placeholders and accepted aliases available for URL query strings.

Placeholders Glossary

Placeholders enclosed in curly braces {...} are dynamically substituted by Perkox with live conversion values before the webhook is fired.

MacroRequirementDescriptionSample Output
{player_id}YesYour user's unique identifier passed when opening the offerwall.user_98214
{reward_amount}YesAmount of virtual currency to credit your user based on your exchange rate.150.00
{payout}RecommendedPublisher revenue earned in USD for this specific conversion.1.50
{click_id}RecommendedYour custom tracking click ID passed from client or generated by Perkox. Used for idempotency and signature.clk_948f2a1b7e09
{conversion_id}RecommendedPerkox unique numerical conversion identifier. Included in canonical HMAC signature.10482
{status}RecommendedConversion status: 'approved' (credit user) or 'chargeback' (revoke credit). Included in HMAC signature.approved
{signature}RecommendedCryptographic HMAC-SHA256 signature calculated over {click_id}|{conversion_id}|{payout}|{status}.249e4f660e8f88...
{transaction_id}RecommendedInternal unique conversion transaction identifier.tx_8f3a92b1c4
{offer_id}OptionalID of the completed offer in the Perkox catalog.5012
{offer_name}OptionalName of the completed offer/campaign.Hero Quest: Legends
{event}OptionalSlug of the goal / tier achieved (e.g. 'install', 'reach_level_10').reach_level_10
{event_name}OptionalHuman-readable label of the event.Reach Level 10
{ip}OptionalIP address of the end user when completing the offer.192.168.1.1
{country}OptionalTwo-letter ISO country code of the user.US
{os_name}OptionalOperating system name (e.g. 'Android', 'iOS', 'Windows').Android
{device_model}OptionalDevice model name reported by client/SDK.Pixel 8 Pro
{sub1} - {sub10}OptionalCustom 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 MacroResolved Perkox TokenBehavior
{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.