Guide - Postbacks

Postbacks: deliver every conversion to your tracker

If you buy traffic through Keitaro or RedTrack, or run offers for an affiliate network, the click leaves your tracker's world the moment it enters Telegram. Registrations and deposits happen where the tracker is blind, and without conversion data your cost reports, auto-rules and payout reconciliation quietly die. Postbacks close the loop: for every conversion Leadgram records, it calls your tracker's S2S URL server-to-server, so the money side of the funnel stays visible where you actually optimize.

How postbacks work

A postback rule is three things: a trigger event, a URL template and an HTTP method. Whenever a conversion event is recorded for one of your clicks, from your advertiser's server-to-server call to the events API, or from an Event Trigger node inside a message flow, every enabled rule matching that event type fires. One event, one rule, one HTTP request.

Postbacks only fire for events that clear billing. A conversion is resolved to charged or free before your rules ever see it - only a subscriber's first billable event is charged, and every later event from that same subscriber is free. If your organization is paused or out of balance when that first charge is attempted, the event lands as blocked instead and no postback fires for it; events from subscribers you've already billed stay free and keep firing. There's no separate status on the rule to flag this, so if a rule that should be firing suddenly goes quiet, check your organization's balance before you start debugging the URL.

Create a rule

  1. Open Postbacks and click Add postback.
  2. Pick a preset: Keitaro and RedTrack prefill a URL template, Custom starts blank.
  3. Name the rule so you recognize it in the table later.
  4. Pick the trigger event: Lead, Registration, Deposit, FTD, Purchase, Bot start or Channel join.
  5. Paste the endpoint URL with macros (see below).
  6. Choose GET or POST. With POST, URL macros still work and the same fields are additionally sent as a JSON body.
  7. Click Add postback to save. The rule is enabled immediately and appears in the table with its event, method, last-fired time and status.
Postback rule form with trigger event and URL templatePostback rule form with trigger event and URL template

URL macros

These placeholders are substituted on every fire:

  • {click_id} - the Leadgram click id; the key your tracker matches the session by
  • {event_type} - the event name (deposit, ftd, and so on)
  • {sub1}-{sub5} - the sub-chain captured on the click
  • {platform} - the campaign's ad platform (meta, google, tiktok)
  • {fbclid}, {gclid}, {gbraid}, {wbraid}, {ttclid} - platform-native click ids

Missing values resolve to an empty string, so &fbclid={fbclid} won't break on Google traffic. Anything not on this list is left in the URL as literal text. A working Keitaro example: https://your-keitaro.com/postback?subid={click_id}&status={event_type}.

Delivery, retries and re-fires

Each fire gets a 10-second timeout, and any HTTP status from 200 to 399 counts as delivered. A failed fire is retried up to 2 more times with growing back-off (3 attempts in total), and every fire is mirrored to a durable ledger you can inspect on Delivery Health:

  • Pending - queued, not delivered yet
  • Sent - your endpoint answered 200-399
  • Failed - the last attempt errored, retries are still possible
  • Dead - all attempts burned; only a manual re-fire revives it

Delivery Health opens with a health summary before you get to any table: one card per rule and per ad-platform connection, with a status badge (Healthy, Failures or Dead letters) plus sent/failed/dead/pending counts for the last 24 hours and the last 7 days. It's the fastest way to spot a rule going bad without reading individual rows.

Below that sits the Problem deliveries table (tabs CAPI | Postbacks), which lists every failed or dead delivery with the exact error, 20 rows per page. It isn't limited to a recent window. That's only true of the health summary counts above it; a delivery that failed months ago still shows up here until you re-fire it or it succeeds. Re-fire queues the delivery again with the same payload. Fix your endpoint first, then re-fire; nothing is lost.

Dedup guarantee: the same logical conversion is never delivered to your endpoint twice. Deduplication holds across queue retries, crashes and event re-processing. A genuinely new repeat conversion (a second deposit reported as a new event) fires again, as it should.

Common pitfalls

  • A rule shows Disabled and never fires. New rules are always created enabled, and today the dashboard only lets you create rules, not edit, disable or delete one after it's saved, so if you see a disabled rule it was toggled off some other way. Use the All / Active / Disabled filter chips to check current state.
  • Macro names are exact: {clickid} (missing the underscore) is not substituted and arrives at your tracker literally.
  • Public http(s) URLs only: localhost and private-network addresses are rejected for security. That check runs when you edit a URL and when the rule fires, but not when you first create it, so a bad URL can get saved and only fail once it actually tries to fire.
  • Your endpoint answering 4xx/5xx turns fires Failed and then Dead. That's on the receiving side: fix it, then re-fire from Delivery Health.
  • The cap is 50 postback rules per organization.