How to Configure Postbacks

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 requesting postback activation, you must complete the following:

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

Step 2: Request Activation #

Postbacks are enabled manually. To request activation, contact us through one of the following:

  • Your dedicated Monetag account manager, or
  • The Support Chat available in your Monetag dashboard

In your request, please include:

  • The name of your Telegram Mini App
  • The main SDK zone ID (this is required)
  • The full postback URL you want to use (this is required)
  • A technical contact (optional, but helpful)

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.