XTRACKER

Webhook payload reference

The exact JSON body XTRACKER POSTs to your webhook for every matched event, field by field, with an example and notes on retries and status handling.

Integration 2 min read

When you add a webhook destination, XTRACKER sends an HTTP request per matched event. This page documents exactly what you receive.

Request

  • Method: POST (configurable to another verb)
  • Content-Type: application/json
  • Headers: any custom headers you configured on the destination
  • Body: the JSON below

Body

{
  "event": "Purchase",
  "canonical": "deposit",
  "event_id": "a1b2c3…",
  "occurred_at_ms": 1765432100000,
  "click": {
    "uid": "abc123",
    "tg_id": 555123,
    "fbclid": "IwAR…",
    "campaign_id": "120…",
    "campaign_name": "promoX",
    "country": "IN"
  },
  "data": {
    "value": "25.00",
    "currency": "USD"
  }
}

Fields

Field Meaning
event The mapped target name from your event map (e.g. Purchase).
canonical The original canonical event (contact / subscribed / registration / deposit).
event_id A stable hash for this event → destination dispatch. Use it for idempotency on your side.
occurred_at_ms Event time in epoch milliseconds.
click Attribution context for the uid: Telegram id, fbclid, campaign fields, country — whatever was captured at click time. May be partially empty.
data Event payload. For deposit it carries value and currency.

Responding

  • Return any 2xx to acknowledge — XTRACKER marks the event sent.
  • Return 408, 429 or any 5xx to ask for a retry (honoured with backoff; a Retry-After header is respected).
  • Any other status (e.g. 400, 404) is treated as permanent — the event won't be retried, so only use those for genuinely unrecoverable input.

Idempotency on your side

Webhooks can be retried, so your handler must be idempotent. Deduplicate on event_id — it's stable across retries of the same dispatch:

if seen(event_id):
    return 200    # already processed
process(body)
mark_seen(event_id)

Security

Webhook URLs are validated to be public (no localhost / private ranges) when the destination is saved, to prevent SSRF. Put a shared secret in a custom header if you want to authenticate XTRACKER on your end.

Next

Keep reading

Playbook

How to find and fix the leak in your funnel

A practical walkthrough: use the funnel breakdown and conversion gauge to pinpoint exactly where users drop off, form a hypothesis, fix one thing, and measure the lift.

3 min read
 Playbook

Keep your finger on the pulse: real-time conversion monitoring

A live dashboard isn't a vanity metric — it's an early-warning system. Here's how watching conversions in real time catches broken funnels and dead campaigns before they burn your budget.

3 min read
 Playbook

Same budget, more deposits: optimizing creatives with per-link data

Clicks lie. Deposits don't. Use per-link attribution to see which creative actually drives revenue — then move spend to the winner and kill the losers.

2 min read