Postbacks and conversions
A conversion reaches Orbitra as a postback from the affiliate network and is attached to a click by its ID (subid). The tracker can then forward it to the traffic source (an outgoing S2S postback) and to the ad platform's Conversions API.
Incoming postback
The postback address is β β Postback URL. It looks like this:
https://your-domain/<postback_key>/postback
postback_key is the installation's secret key (protection against fake conversions). If it still equals the public default value from the repository, the panel warns you; generate a new one on the same page or with php cli/generate_postback_key.php. The installer generates its own key.
Parameters
| Parameter | Required | Meaning |
|---|---|---|
subid | yes | Tracker click ID β what the network received in {subid} / {clickid} |
status | no | Conversion status: lead, sale, rejected, registration, deposit, trash, or any custom one |
payout | no | Payout amount |
currency | no | Payout currency |
tid | no | Transaction ID β for repeated conversions on the same click |
sub_id_N | no | Additional values |
<type>_status | no | Map statuses right in the URL: sale_status=approved,confirmed |
Examples:
β¦/postback?subid={subid}&status=lead
β¦/postback?subid={subid}&status=sale&payout={payout}
β¦/postback?subid={subid}&status=sale&payout={payout}&tid={transaction_id}
β¦/postback?subid={subid}&status={status}&sale_status=approved,confirmed
If the network names its parameters differently, set up parameter aliases on the same page.
Responses
200 β the conversion is recorded. 4xx β the request is rejected (wrong key, unknown click). 500 / 503 β a write error; the network should retry the postback. The conversion, its counters and the Conversions API events are written in a single transaction: an error can never produce a "200 and a lost event".
How the status is determined
In order:
- Conversion types from Settings β Conversion Types β if the status is in a type's value list.
- A built-in type with the same name.
- The
<type>_status=β¦rule from the postback itself. - Built-in aliases:
approved,confirmed,accepted,convertedβsale;declined,refused,cancelled,canceledβrejected. - Otherwise β
custom.
Statuses that did not match any type are listed under Settings β Conversion Types β Unmapped statuses: you can map them to a type there, and already recorded conversions get reclassified.
Conversion types
Each type has: a name, a list of statuses from the network, a label color, and four flags β counts toward "Conversions", counts toward "Profit", send S2S to the source, counts toward the offer Cap. A Revshare type exists out of the box (the revshare status goes into profit only: no new conversion, no S2S, no Cap).
Payouts in another currency
The payout is converted to the tracker's base currency (rates in core/CurrencyRates.php). The original amount, currency and rate are stored on the click. The outgoing postback macros {payout} / {currency} carry the value in the base currency; the original ones are {fx_orig_payout} / {fx_orig_currency}. An unknown currency pair is recorded as is.
Incoming postback log
β β Logs β Postbacks β every incoming request with its outcome: whether the click was found, the resulting status, the amount. The click ID opens the click card.
Outgoing S2S postbacks (to the traffic source)
Configured in the campaign, on the S2S Postbacks tab. Each postback is a card: URL, GET or POST method, status chips (sale, lead, rejected, registration, deposit, trash plus custom ones). The "insert macro" menu inserts a macro at the cursor position.
If the selected traffic source has a postback_url set, a campaign with an empty list receives it automatically. If postbacks are already configured, a hint with an "add" button appears at the top of the tab.
The status filter passes a conversion through if the internal status matched (sale), the network's own word (approved), or the legacy custom chip for words that are now recognized by aliases.
Macros
{subid} (also {clickid}, {click_id}), {status}, {payout} (also {conversion_revenue}), {currency}, {tid} (also {external_id}), {campaign_id}, {offer_id}, {cost}, {revenue}, {profit}, and any saved click parameter by name: {sub_id_1} β¦ {sub_id_30}, {fx_orig_payout}, {fx_orig_currency}, etc.
{status} carries the internal status (sale), not the network's original word. To translate it into the source's vocabulary, use a Keitaro-style transformation: {status: sale=purchase lead=lead} β a status not in the list goes through unchanged.
Delivery queue
Outgoing postbacks are not sent at the moment of conversion β they go into the s2s_postbacks_log queue, and the postback_queue_cron.php cron (once a minute) delivers them with retries:
- success β HTTP 2xxβ3xx;
- retries: 60 s β 5 min β 30 min β 2 h β 24 h, after which the row is marked
failed; - SSRF check on enqueue and before sending: an address in a private network gets
failedimmediately; - a row left in
in_flightby a crashed worker returns to the queue after 10 minutes.
β οΈ Without the cron, the queue is never processed. The installer sets it up; to check or add it manually β Settings β Automation β Postback Queue. Updating through the panel also restores a missing cron.
Queue log: β β Logs β S2S (status, attempts, next attempt, last error, HTTP code).
Postback tester
The button on the S2S Postbacks tab (admin only) sends a real postback to this same server with a one-off click and shows a verdict for every step:
- which status the conversion was recorded with;
- whether each S2S postback's status filter passes it β and why: by internal status, by the network's word, or by the legacy chip;
- a trial delivery to the source: HTTP code and timing;
- macros that would not resolve and would go to the source as plain text (
{external_id},{sub_id_N}); - placeholders from the source template (
bbg=xxx,[YOUR_β¦]); - whether the queue worker is alive and the cron is installed.
The test click, conversion and queue rows are deleted after the check.
Re-sending missed conversions
The "Re-send missed conversions" button enqueues conversions from the last 72 hours that pass the current filter but never made it into the queue. Pressing it again duplicates nothing.
Conversion import
β β Conversion Import β upload a file or paste a list of click IDs when the network cannot send postbacks, or when they need to be restored.
Conversions API
Sending conversions to Meta and TikTok servers is configured in the pixel profile and in the campaign (the "Integrations" tab). For details on Meta, see Facebook / Meta. Events are enqueued together with the conversion and delivered with confirmation: success only on a 2xx response where events_received matches the batch size.
Monitoring
conversion_monitor_cron.php computes the failed-postback share over a window (60 minutes by default) and, when the threshold (10%) is exceeded, writes an alert to var/logs/conversion_alerts.log; sending the alert to Telegram is not implemented yet. The installer does not set up this cron β add it if needed:
*/5 * * * * php /var/www/orbitra/conversion_monitor_cron.php --quiet
Quick start: your first campaign
The short path: install the tracker, create a campaign, and get your first clicks and conversions in under an hour.
Read guide βDocsInstallation and updates
Install Orbitra on a fresh Ubuntu or Debian server with one command, and update to new versions safely.
Read guide βDocsMigrating from Keitaro
Move campaigns, offers, sources and domains from Keitaro to Orbitra in one click β what transfers and what to check.
Read guide βDocsMigrating from Binom
Move campaigns and streams from Binom to Orbitra: what transfers automatically and what to set up by hand.
Read guide βDocsFeature overview
Everything Orbitra can do: campaigns and streams, cloaking, landings, PWA, postbacks, costs, reports and integrations.
Read guide βDocsCampaigns and streams
The complete reference: campaign settings, stream types, schemas, rotation, filters, test links and every option explained.
Read guide βDocsCloaking
Full cloaking reference: detection layers, global settings, per-stream filters, verdicts and reports.
Read guide βDocsBrowser check
How the JS check catches bots, VMs and emulators through contradictions in the browser environment.
Read guide βDocsLanding pages
Landing types, the {offer} macro, the JS adapter, LeadForge and multi-offer landings β the complete reference.
Read guide βDocsPWA and Web Push
Build installable PWA apps and collect push subscribers: settings, icons, events and notifications.
Read guide βDocsPWA Funnel
A multi-step PWA funnel: install prompts, event tracking and re-engagement notifications.
Read guide βDocsConversion popups
Show real conversion events as on-page popups: setup, triggers and placement.
Read guide βDocsSession recordings and heatmaps
Replay real visits and see click and scroll maps. Storage limits and privacy notes.
Read guide βDocsContent gallery
Central storage for icons, screenshots and creatives used across PWAs and landings.
Read guide βDocsCreatives library
Store creatives with subid tracking and test them across campaigns.
Read guide βDocsExternal PWA and Telegram channels
Publish PWAs to external domains and run Telegram channels as a traffic source.
Read guide βDocsPostbacks and conversions
Incoming postbacks, conversion statuses and types, and outgoing S2S postbacks to your traffic source.
Read guide βDocsCosts
Import spend from Facebook, TikTok and Google Ads, or update it via API and cron β and how the revenue aggregator works.
Read guide βDocsPush and pop networks
Working with push and pop traffic sources: feeds, zone optimization and the zone killer.
Read guide βDocsFacebook / Meta
Cost import from Meta Ads and the Conversions API: server-side events with deduplication.
Read guide βDocsDolphin / Fbtool
Receive Facebook costs through the Dolphin (Fbtool) API in real time.
Read guide βDocsFB comment cleaner
Bulk-moderate comments under Meta ads: hide, delete and filter by keywords.
Read guide βDocsTraffic sources and affiliate networks
Catalog of 50+ traffic sources and 440+ networks: templates, parameters and postback URLs.
Read guide βDocsReports, logs and metrics
The report builder, saved reports, click logs and every metric explained.
Read guide βDocsDomains and SSL
Add domains, DNS, free Let's Encrypt certificates, redirects, parking and every switch on the page.
Read guide βDocsCloudflare
How to run campaign domains through Cloudflare: DNS, SSL modes and what to turn off.
Read guide βDocsAdministration
Users, roles and permissions, security settings, geo databases, updates and system health.
Read guide βDocsTelegram bot
Manage the tracker from Telegram: stats, conversions and alerts in chat.
Read guide βDocsMCP: an AI assistant in the tracker
Connect Claude or any MCP client to Orbitra and manage campaigns with plain-language commands.
Read guide β