> For the complete documentation index, see [llms.txt](https://docs.perkox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkox.com/getting-started/apps/postback-url-configuration.md). # Postback URL Configuration The **Postback URL Configuration** section is where you set up postback URLs to track conversions and other events in real-time. This step is critical for monitoring user activity, optimizing campaigns, and ensuring accurate reward distribution. Below is a detailed breakdown of each field and its purpose: *** ### **1. Enter Postback URL** * **Purpose**: This is the URL where conversion and event data will be sent. It allows you to track user actions like clicks, conversions, and rewards. * **Placeholders**: You can use dynamic placeholders in the URL to insert specific data points. For example: * `(player_id)`: Unique identifier for the user. * `(click_id)`: Unique identifier for the click event. * `(offer_id)`: Unique identifier for the offer. * `(status)`: Status of the conversion (e.g., success, failure). * `(reward_amount)`: Amount of reward earned by the user. * `(sub1)` to `(sub5)`: Additional custom parameters for tracking. #### ***
## Postback Setup Postbacks allow your app or backend to receive real-time reward and conversion updates from Perkox. When a user completes an offer or reward event, Perkox can send a request to your server with details such as the player ID, click ID, reward amount, payout, and conversion status. Use postbacks to automatically credit users inside your app or game. *** ### How Postbacks Work Basic flow: ``` User opens offerwall→ User clicks an offer→ User completes the required action→ Perkox validates the event→ Perkox sends a postback to your server→ Your backend credits the user ``` Your postback URL should be created inside your publisher dashboard. *** ### Example Postback URL You can use placeholders inside your URL to dynamically receive conversion data. Example: ``` https://example.com/postback?user_id={player_id}&click={click_id}&points={reward_amount}&payout={payout}&status={status} ``` When a conversion happens, Perkox replaces the placeholders with real values. Example result: ``` https://example.com/postback?user_id=player123&click=d4246e2ca2894efc79df7b4b4&points=50.00&payout=10.00&status=approved ``` *** ### Method Type Perkox supports: #### GET — Recommended Use GET if you want a simple and fast postback integration. ``` GET https://yourdomain.com/postback?user_id={player_id}&click={click_id} ``` #### POST Use POST if your backend requires conversion data to be sent in the request body. Recommended for advanced backend systems. *** ## Placeholder Glossary Use these placeholders in your postback URL. | Placeholder | Description | Example | Required | | ----------------- | ----------------------------------- | --------------------------- | -------- | | `{player_id}` | Player/user ID passed from your app | `player123` | Optional | | `{click_id}` | Unique click ID for the conversion | `d4246e2ca2894efc79df7b4b4` | Optional | | `{offer_id}` | Offer ID related to the conversion | `10101` | Optional | | `{reward_amount}` | Reward amount credited to the user | `50.00` | Optional | | `{payout}` | Publisher payout amount | `10.00` | Optional | | `{ip}` | User IP address | `192.168.1.1` | Optional | | `{status}` | Conversion status | `approved` | Optional | *** ## Recommended Postback Template Use this template for most integrations: ``` https://yourdomain.com/perkox/postback?user_id={player_id}&click_id={click_id}&offer_id={offer_id}&reward={reward_amount}&payout={payout}&status={status} ``` This gives your backend enough information to: * identify the user * validate the click * track the offer * credit the correct reward * store payout and status data *** ## Integration Credentials Inside the **Apps** section, each app/property includes integration credentials. You may see: ``` App ID: 83f34460********SDK Key: 82116454********API Key: api_561f******** ``` ### App ID The App ID identifies the app or property inside Perkox. Use it when connecting your app to the Perkox SDK. ### SDK Key The SDK Key is used to activate the Perkox SDK inside your app. Keep this key private and do not expose it publicly. ### API Key The API Key is used for server-side or backend communication. Only use this key from secure server environments. Never place the API Key inside public frontend code. *** ## Important Security Notes To protect your integration: * never expose API keys publicly * validate postbacks on your backend * store click IDs and player IDs securely * prevent duplicate reward credits * log all postback events * check conversion status before crediting rewards Recommended backend logic: ``` Receive postback→ Check click_id→ Check player_id→ Check status→ Prevent duplicate credit→ Credit user reward→ Store event in database ``` *** ## Reward Status Handling Your backend should handle different statuses. Example: | Status | Meaning | Recommended Action | | ---------- | -------------------------- | ----------------------- | | `approved` | Conversion is valid | Credit the user | | `pending` | Conversion is under review | Wait before crediting | | `rejected` | Conversion is invalid | Do not credit | | `reversed` | Conversion was reversed | Remove or adjust reward | If your current status system is different, adapt this table to match your dashboard logic. *** ## Testing Your Postback Before going live, test your postback URL. Checklist: * postback endpoint is live * URL returns HTTP `200` * player ID is received correctly * click ID is stored * reward amount is parsed correctly * duplicate conversions are blocked * rejected conversions are not credited * logs are visible on your backend *** ## Common Issues ### Postback not received Check: * URL is correct * endpoint is publicly accessible * server firewall allows requests * SSL certificate is valid * method type matches your backend ### User not rewarded Check: * `{player_id}` is being passed correctly * backend is parsing reward amount * status is approved * duplicate prevention is not blocking valid events ### Wrong reward amount Check: * `{reward_amount}` placeholder is mapped correctly * your app currency conversion is configured correctly * backend is not overriding values *** ## Best Practices For best results: * always pass a stable `player_id` * store every `click_id` * use server-side reward validation * keep logs for all reward events * test with small reward values before launch * monitor conversions daily after going live *** ## Related Documentation Pages Recommended GitBook structure: ``` Offerwall Integration├── Overview├── Create Your App├── SDK Credentials├── Set Up Offerwall├── Configure Rewards├── Postback Setup├── Placeholder Glossary├── Reward Statuses├── Testing & Debugging└── Best Practices ``` * **Testing**: After setting up the postback URL, test it by simulating user actions (e.g., clicks, conversions) and verifying that data is sent correctly. * **Error Handling**: Ensure your server can handle errors (e.g., invalid data, missing parameters) to avoid disruptions in tracking. * **Security**: If using sensitive data, consider using the POST method or encrypting the data for added security.