Postbacks #

A postback is an HTTP request that Monetag sends to your server after an ad event in your Mini App is confirmed. You don’t write tracking code for it: Monetag records the impression or click, checks it and calls your URL with the result. On your side it takes one URL with macros, set for your main zone in the Monetag SSP.

Each postback tells your server:

• what happened: impression or click, and which zone delivered the ad;
• whether the event is paid: reward_event_type is valued or non_valued;
• the estimated earnings for the event, estimated_price;
• the ymid you passed to the SDK, and the Telegram user ID when Telegram provides it;
• where in your UI the ad was shown, request_var. Its value depends on the format, see the Macro Reference.

If your server does not accept a postback, Monetag retries it for up to about 38 hours.

Postbacks are sent for Rewarded Interstitial, Rewarded Popup and In-App Interstitial. In-App Interstitial sends impression postbacks only, no click.

How It Works #

%%{init: {"sequence": {"width": 110, "actorMargin": 30}}}%%
sequenceDiagram
    autonumber
    actor U as User
    participant A as Mini App
    participant M as Monetag
    participant S as Your server
    A->>U: show_XXX({ ymid })
    U->>A: Watches or clicks
    A->>M: Impression or click
    Note over M: Confirms the event:<br/>valued or non_valued,<br/>estimated price
    par Postback
        M->>S: GET postback URL
        Note over S: Reward once per ymid<br/>if valued
        S-->>M: 2xx, or a retry
    and Frontend Callback
        M-->>A: Promise resolves
    end

1. Your app calls show_XXX() with a ymid that is unique for this ad show, and the SDK shows the ad.
2. The user watches or clicks the ad.
3. The impression or click reaches Monetag. Monetag confirms the event and decides whether it is paid.
4. Monetag sends a GET request to your postback URL, with the macros replaced by the event data. Your server grants the reward if reward_event_type is valued, once per ymid.
5. Your server answers with 2xx. Otherwise Monetag retries the postback.
6. In parallel, for Rewarded Interstitial and Rewarded Popup, the SDK Promise in your app resolves with a subset of the event data: ymid arrives as variable2, and estimated_price is absent for non_valued events. See What You Get in the Callback. The Promise and the postback are delivered independently, so don’t rely on their order.

Example request for a Rewarded Interstitial impression:

GET https://your-backend.com/postback?secret=YOUR_SECRET&ymid=user-42_ad_7&event_type=impression&reward_event_type=valued&zone_id=123456&sub_zone_id=123456&request_var=bonus_button&telegram_id=123456789&estimated_price=0.0037000

Why Not Reward on a Request from Your App #

A common alternative is to let the app tell your server that an ad was shown, for example after show_XXX() resolves, and grant the reward on that request. The request comes from the user’s device, and this is where it breaks:

flowchart TB
    subgraph app["Request from your app"]
        direction TB
        a1["Ad is shown"] --> a2["App asks your<br/>server for a reward"]
        a2 --> a3["Reward granted,<br/>paid or not?"]
        x1["Forged request<br/>devtools, script"] -.->|"no ad watched"| a2
        a2 -.->|"app closed"| x2["Request lost"]
    end
    subgraph pb["Monetag postback"]
        direction TB
        b1["Ad is shown"] --> b2["Monetag confirms<br/>the event"]
        b2 --> b3["Postback with<br/>valued / non_valued,<br/>estimated price"]
        b3 --> b4["Reward granted<br/>only if valued"]
        b3 -.->|"no 2xx: retries<br/>up to ~38 h"| b3
    end
    app ~~~ pb
    classDef risk fill:#fdecea,stroke:#c62828,color:#000
    classDef ok fill:#e8f5e9,stroke:#2e7d32,color:#000
    class x1,x2,a3 risk
    class b4 ok

This holds even if the app sends its request after the SDK Promise resolves: the Promise result is confirmed by Monetag, but the request to your server still comes from the user’s device.

Postback and Frontend Callback #

When you call show_XXX(), the SDK returns a Promise. This mechanism is known as a Frontend Callback.

For Rewarded Interstitial and Rewarded Popup on zones with reward postback (enabled by default), the Promise resolves with the event data after Monetag confirms the event. It rejects with Failed to verify the ad show if no confirmation arrives. For In-App Interstitial and for the preload and start types, it resolves with no value.

show_XXX().then((result) => {
  // Frontend Callback triggered
  // Reward the user if result?.reward_event_type === 'valued'
});

Backend confirmation is on by default for rewarded formats. It can be turned off per SDK zone on request.

⚠️ Important: A resolved Promise does not mean the event was monetized. Check reward_event_type in the result.

Use the Frontend Callback for the UI and the postback for rewards and accounting. You can use both in parallel.

Set It Up #

1. How to Configure Postbacks: the URL in the SSP and your endpoint.
2. Macro Reference: every value a postback can carry.
3. Types of Postback Events: what impression and click mean for each format.
4. Testing and Verifying Postbacks: how to check your setup.