How to Configure Postbacks #

Monetag’s server-side postback system allows you to receive HTTP notifications when an ad event — such as an impression or a click — is confirmed and processed by our backend.

This mechanism is essential for apps that offer user rewards, perform custom analytics, or rely on server-side validation of ad interactions.

⚠️ Postbacks are currently available only for reward-based ad formats:
✅ Rewarded Interstitial
✅ Rewarded Popup
❌ Not supported for In-App Interstitial

Step 1: Prepare Your App #

Before configuring postbacks, make sure that:

Your Telegram Mini App (TMA) is added to your Monetag account.
The SDK is properly integrated and activated for that app.
You have the main SDK zone ID from your Monetag dashboard.

Step 2: Configure Postback URL in SSP #

Postbacks can now be configured directly in the Monetag SSP:

Postback configuration example

Go to your main SDK zone settings
Find the Postback URL field
Paste your endpoint URL with macros (see below)
Save the changes

Postback macro example

Each SDK can have its own postback configuration.
If your Mini App uses multiple ad formats (e.g. Interstitial + Popup), the {sub_zone_id} macro will help you distinguish which zone triggered the postback.

Step 3: Prepare Your Postback URL #

Monetag will send a GET request to your endpoint for each confirmed monetized ad event.

You can use macros in your URL — these will be replaced with event-specific values by Monetag.

Example:

https://yourdomain.com/postback?ymid={ymid}&zone={zone_id}&event={event_type}&value={reward_event_type}&amount={estimated_price}

📖 See the Macro Reference section for a full list of available placeholders.

Step 4: Implement the Endpoint #

Your backend must accept GET requests and parse the query parameters.

Example (Node.js):

app.get('/postback', (req, res) => {
  const { ymid, event_type, reward_event_type, estimated_price } = req.query;

  if (reward_event_type === 'valued') {
    rewardUser(ymid, estimated_price);
  }

  res.sendStatus(200);
});

We recommend:

Logging all postbacks
Ensuring idempotency via ymid
Always returning 200 OK for successful processing

Step 5: Understand Retry Behavior #

If your server does not respond with 200 OK, Monetag will retry the postback several times with increasing intervals.

Retries are automatic and reliable
Retry duration and limits may vary
Make sure your endpoint is available and efficient

Best Practices #

To ensure correct and secure processing:

✅ Always use a unique ymid per ad event
✅ Validate all parameters to prevent abuse or broken logic
✅ Use HTTPS and avoid redirects
✅ Log all postbacks for monitoring and debugging
✅ Ensure idempotency by using ymid to avoid duplicate rewards

Once your setup is complete, test postbacks by triggering real ad views in your app.