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.