An S2S postback (server-to-server postback) is a way for an advertiser’s system to send conversion data directly to PalDock’s servers without relying on browser pixels or cookies. It ensures more accurate tracking, especially on mobile or cookie-restricted environments, by securely passing conversion details like IDs, results, or any values from the advertiser to PalDock in real time.
You can create custom S2S postbacks if needed, but by default, a global S2S postback exists. Any S2S postback can include conditions that determine whether the information will be accepted:
- Source – All, Link, Iframe, API
- Conversion type – All, Lead, Sale, Custom
- Affiliate – All or specific
- Advertiser – All or specific
- Offer – All or specific
The global S2S postback has all conditions set to All. Postbacks are listed in the postback table, with country categorization inherited from the Offer. If no or multiple Offers are selected, the global country is applied and the category remains blank.
Sequence steps
Sometimes, the advertiser may only send limited information (e.g., that a conversion changed but without details), expecting you to request the missing data.
In such cases, you can use:
- Tracking API – combines webhooks (postbacks) and HTTP requests, but does not support the conditions listed above.
- Sequence Steps – a Connection Creator feature applied to S2S Postbacks, allowing you to use both postback conditions and follow-up steps together.
Sequence Steps are optional. If they exist in the Postback, the Postback ID becomes mandatory. Without it, the steps won’t run. The Postback request is still received, but follow-up steps are skipped. Advertisers need to include a Postback ID when Sequence Steps are configured (e.g., in the query ?id=value).
Tracking processing
As mentioned in Tracking processing, when a tracking request is received, it must be processed. The main parameters are:
- PalDock Conversion ID – pcid – identifies the PalDock click (clickID) or lead (leadID).
- PalDock Advertiser ID – advertiser_id – the unique advertiser ID available in the admin.
- Advertiser External ID – external_id – e.g., the external lead ID on the advertiser’s side, sent together with the conversion. It is used for deduplication (ensuring only one conversion is created), so we always recommend sending it.
- Commission ID (optional) – commission_id – the commission ID in PalDock. Required if multiple commissions exist for the same conversion type. If not provided, the default (first in order for that conversion type) will be used.
Required fields depend on the chosen pairing method:
- Via PalDock Conversion ID – only this parameter is required, since it is always unique in the system.
- Via Advertiser External ID – the External ID is required. On its own, it may not be unique, but uniqueness is ensured in combination with the PalDock Advertiser ID.
For affiliate links, the external ID is not known in advance, so only the PalDock conversion ID can be used.
For iframe and API integrations, both methods are supported. If you are using links together with iframes or APIs, you may find it easier to implement the same tracking method across all of them, although this is not required.
Conversion type
Each conversion type (including custom ones) can be used in two ways:
- To create a conversion
- To update a conversion
This is done by using the parameter action, which defines whether the conversion should be created (create) or updated (update).
Parameters
The most used parameters are:
- type – defines the conversion type in PalDock. Required when creating a new conversion.
Example: lead, sale, or a custom type - commission_id – specifies which commission to apply if multiple commissions exist for the same conversion type.
Example: 9e321d3b-3690-4100-821d-86476cc4c2fb - value – order value passed from the shop, used when commissions are percentage-based (e.g. 5% of order value). Can also be used like commission.
Example: 0.5, 12343 - commission – direct commission amount for a specific lead, bypassing the need for calculation. Can also be used like value.
Example: 0.5, 12343 - price – price received from the advertiser (typically passed through in cascades, if available).
Example: 0.5, 12343 - result – status of the transaction. Updating this field updates the tenant result and automatically cascades to related transactions and payouts.
Possible values: approved, rejected, pending - action – defines whether a new conversion should be created or an existing one updated.
Possible values: create, update
Default: update (if type is present and action=update is not, then action=create is applied)
You can use dozens of parameters, as listed on the Parameters page.
Example
Required fields depend on the chosen pairing method:
Via PalDock Conversion ID
Only the PalDock Conversion ID (eid) is required, since it is always unique in the system.
https://api.paldock.com/api/tenant-name/postbacks/handle?eid={paldock_conversion_id}&external_id={your_external_id}&type={conversion_type}&result={approved|rejected|pending}&action={create|update}
Via Advertiser External ID
The Advertiser External ID (external_id) is required. On its own, it may not be unique, but uniqueness is ensured in combination with the advertiser_id. It’s used also for deduplication.
https://api.paldock.com/api/tenant-name/postbacks/handle?advertiser_id={advertiser_id}&external_id={your_external_id}&type={conversion_type}&result={approved|rejected|pending}&action={create|update}