Skip to Content
Track your Telegram conversions with Meta Ads - Get started in minutes!
API ReferencePostbacks

Outgoing postbacks

Postbacks send new AdTarget conversion events to your server. They are separate from the incoming REST API: existing API keys, requests, attribution and advertising-platform delivery continue to work.

Telegram events

The first section forwards raw Telegram updates, not advertising conversions. Choose a destination and select business_message (Business DMs), business_connection, chat_join_request, and/or chat_member (joins, leaves and status changes).

Configuration belongs to a bot across the account, not just one website. The destination receives message content and Telegram identities in the selected updates. Only configure a backend you control. The delivery history belongs to the site where the destination was initially configured.

New generic relays send a JSON body containing update_id and the selected Telegram update object, unchanged. They use the X-AdTarget-* signature and delivery headers described below, a durable queue and up to six attempts. Repeated Telegram update IDs are deduplicated within retained delivery history. They do not create Lead, Purchase or other advertising events.

Existing TSA / Ross integration

The existing TSA relay is displayed with its current URL and enabled Telegram types. It keeps the existing /telegram/proxy destination, X-Forward-Secret / X-Forward-Timestamp authentication, raw Telegram payload with provenance enrichment, and its existing retry policy. It does not use the generic HMAC protocol or the new conversion switches. It remains the sole sender for TSAWelcomeBot; no automatic second sender, secret rotation, replay or receiver migration occurs. Its earlier deliveries are not retroactively added to the generic delivery history.

This protected existing integration is read-only in this editor. It is intentionally not replaced when enabling new relays for other bots.

Conversion events (optional)

Expand Conversion events — optional to forward new AdTarget conversion records, including conversions received through the incoming REST API. These switches do not control the Telegram relay above.

Configure conversion delivery

Open Site → Settings → Postbacks, enter one public HTTPS URL, select the event types and enable delivery. Save, copy the signing secret shown once, then choose Send test. The queue normally starts deliveries within one minute. Only the site owner can change the configuration; administrator preview is read-only.

Supported types: Lead, Purchase, CompleteRegistration, Subscribe, Contact, and Custom. Selecting Custom includes all custom names; use data.customEventName to distinguish them. These are conversion types, not pageviews, raw Telegram joins/leaves or derived business stages such as QFTD. A join uses the conversion event configured for that channel.

Only new conversions created after activation are sent. Existing history, later value edits and already-existing conversions reused by the incoming API are not replayed. No historical migration is needed. Events without a resolved site cannot be delivered to a site’s endpoint.

Saving settings cancels outstanding deliveries from the previous configuration. Disabling stops queued deliveries; a request already in flight may finish. Use a public hostname resolving to IPv4 on HTTPS port 443. Private addresses and redirects are blocked.

Request

AdTarget sends POST with Content-Type: application/json:

{
  "version": 1,
  "event": "Purchase",
  "occurredAt": 1789300000000,
  "data": {
    "conversionId": "conversion-id",
    "websiteId": "atid_example",
    "telegramUserId": 123456789,
    "value": 97,
    "currency": "EUR",
    "contentName": "VIP"
  }
}

occurredAt is Unix time in milliseconds. Optional fields are omitted when absent. Names, email addresses, phone numbers, IPs, API keys and advertising credentials are not included. A test uses event: "test" and a sample message; it does not create a conversion or send anything to your advertising pixels.

Verify authenticity

Store the secret on your server. Check these headers:

  • X-AdTarget-Delivery-Id: stable across retries; use it to deduplicate processing.
  • X-AdTarget-Timestamp: Unix time in seconds, refreshed on each attempt.
  • X-AdTarget-Signature: sha256= followed by the hex HMAC-SHA256 of timestamp + "." + rawRequestBody, signed with your secret.

Verify the signature against the original body bytes before JSON parsing, reject timestamps outside a five-minute window, and compare signatures in constant time. Atomically store the delivery ID with your business operation so a retry cannot repeat it. Return a 2xx status after durably accepting the request.

Reliability

Delivery is at least once, not exactly once. A timeout after your server accepted an event may cause a duplicate. There are up to six total attempts, with increasing delays. HTTP redirects and other non-2xx responses count as failures. DNS resolution is limited to five seconds and the HTTP request to ten seconds.

Delivery history shows the latest 50 requests, attempts, status and HTTP code. Completed history is retained for 30 days. A failed postback does not change the incoming API response or the Meta/TikTok/Snapchat conversion-delivery status. Avoid loops: do not feed every outgoing postback back into AdTarget as a new incoming event.

Last updated on
Conversions APIOverview