Postback Troubleshooting & FAQ

Postback Troubleshooting & FAQ #

When working with postbacks in Telegram Mini Apps via the Monetag SDK, you may encounter various integration issues or have recurring questions. This section helps you diagnose problems and clarify the behavior of the postback system.

Common Issues #

Postbacks not received #

  • Ensure that postbacks are correctly configured in your SDK zone settings inside the Monetag SSP.
  • Verify that your zone is configured for a supported format (Rewarded Interstitial, Rewarded Popup or In-App Interstitial).
  • Confirm that the ad was actually shown or triggered inside your app (not just preloaded).
  • Make sure your postback URL is valid, uses HTTPS, and your server is publicly accessible without authentication.

Postback retries not working #

  • A 2xx response counts as delivered. Redirects are not followed, so a 3xx response counts as a failure.
  • If your server answers with a status of 300 or higher or does not answer within 30 seconds, Monetag retries the postback after 1, 5, 15, 30, 60, 90, 120 and 180 minutes, then after 30 hours. Each wait counts from the previous attempt.
  • After a connection error (connection refused, DNS failure), Monetag retries once, after 30 hours.
  • After the last retry the postback is dropped.
  • Return a 2xx status (for example 200 OK) after you save the event. Do not redirect.
  • Review your server logs to ensure retry requests are not blocked by firewalls or rate limits.

Duplicate postbacks #

  • Retries may result in repeated delivery if your server fails to acknowledge correctly.
  • Always ensure your postback handler is idempotent — deduplicate using the ymid field.

Missing or unexpected macro values #

  • Some macros (e.g. {telegram_id}) may be empty if the Telegram WebApp SDK didn’t provide them.
  • Always log incoming postback data and validate before applying business logic.
  • Use fallback logic where appropriate (e.g. default user ID if telegram_id is missing).

Frequently Asked Questions #

Can I get postbacks for In-App Interstitial? #

Yes. In-App Interstitial sends impression postbacks. It does not send click.

What is reward_event_type and how should I use it? #

This field reflects the monetization status of the event:

  • valued — the event was monetized and revenue was generated.
  • non_valued: the event is not paid (for example fraud or fallback traffic).

Only valued events should trigger user rewards or count toward revenue.

Is telegram_id always available? #

No. The SDK attempts to extract the Telegram user ID via the WebApp context, but it may be unavailable in some sessions or devices. Always treat telegram_id as optional.

Do I need to use both frontend .then() and server-side postbacks? #

It depends on your logic:

  • Use .then() to update the UI (e.g. show “Reward granted” or unlock content).
  • Use postbacks for reward validation, revenue tracking, and analytics in your backend.

We strongly recommend using both: frontend for user experience, postback for verified data and backend rewards.

How can I test my integration? #

See Testing and Verifying Postbacks for detailed step-by-step instructions on how to simulate and verify successful postback delivery.