Server-Side Postbacks #

A server-side postback is an HTTP request sent from Monetag to your server confirming that a user has performed a specific ad-related action — such as viewing or clicking an ad. This mechanism is essential for triggering rewards, validating events, and syncing your analytics with Monetag’s monetization system.

Unlike the .then() method in the SDK, which fires immediately after an ad attempt on the frontend, a server-side postback is triggered only after Monetag has confirmed the event internally.

When to Use Postbacks #

Use server-side postbacks when you need to:

Grant rewards reliably from your backend
Log or analyze monetized user actions
Match events to users or sessions using your own identifiers
Validate real interactions and protect against fraud

Supported Event Types #

Currently, Monetag supports postbacks for two main events:

Event Type	Description
`impression`	A successful ad impression
`click`	A confirmed ad click (e.g., Popup)

Event availability may vary by ad format and integration settings.

Example Postback Request #

GET https://your-backend.com/postback?ymid=user123&event=click&zone_id=8790478&request_var=bonus-btn

Postback Parameters #

Parameter	Description
`ymid`	A unique identifier passed from your app via SDK (`user_id`, `uuid`, etc.)
`event_type`	The type of event: `impression` or `click`
`zone_id`	The ID of the ad zone where the event occurred
`request_var`	Optional identifier for the trigger placement (e.g., a button or screen name)

Sending `ymid` from SDK #

To link postbacks with specific users or actions, pass a ymid when calling the ad from your app:

show_XXX({ ymid: 'user-123', requestVar: 'bonus-button' })

You can use:

A user ID
A session ID
A random UUID
Any unique string meaningful to your backend

If ymid is not set, the SDK will try to use the Telegram user ID, but only if the Telegram WebApp API is initialized and accessible in your app.

Example Postback URL #

https://yourdomain.com/postback?uid={ymid}&source={request_var}&event={event_type}

Backend Implementation Examples #

Node.js (Express) #

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

  console.log(`[Postback] ymid=${ymid}, event=${event_type}, zone_id=${zone_id}`)

  if (event_type === 'click') {
    rewardUser(ymid)
  }

  res.sendStatus(200)
})

PHP #

<?php
$ymid = $_GET['ymid'] ?? null;
$event = $_GET['event_type'] ?? null;

if ($event === 'click') {
    reward_user($ymid);
}

http_response_code(200);

Python (Flask) #

from flask import Flask, request

app = Flask(__name__)

@app.route("/postback")
def postback():
    ymid = request.args.get("ymid")
    event = request.args.get("event_type")

    print(f"[Postback] ymid={ymid}, event={event}")

    if event == "click":
        reward_user(ymid)

    return "", 200

How to Enable Postbacks #

To configure postbacks, please contact your account manager or reach out to Monetag support.
Currently, postback setup is done manually through our internal system, but we are actively working on making this process self-service in the near future.

Best Practices #

Recommended:

Use a unique ymid for each ad call to track sessions accurately
Whitelist Monetag IPs or use secret keys to validate requests
Implement deduplication on your backend in case of repeated postbacks
Log both valid and failed postbacks for analysis
Use request_var to identify where in the UI the ad was shown

Avoid:

Relying only on .then() for business logic — use postbacks for confirmation
Using sub-zone IDs in the SDK — only use your main zone ID
Ignoring user/session-level tracking — postbacks are most powerful when linked to data you control

Server-side postbacks are a reliable, transparent way to connect monetization events to your backend logic. They allow for accurate reward distribution, better analytics, and scalable monetization infrastructure for Telegram Mini Apps.