Handling Postback Events
Postbacks are notifications sent to your designated URL whenever a revenue event associated with an Offer is recorded. This guide explains how to set up and handle these events.
You can access the AdsPostX Dashboard to set your postback URL. For more detailed information, view the following playable demo:
The postback URL receives the following information:
- Offer ID and associated advertiser's name (if available)
- Revenue from the Offer conversion or click event
- Payload data that was supplied when the Offer was served. (Learn more about Passing Payload Values)
- Timestamp of the conversion
If the engaged Offer has the LoyaltyBoost (Rewarded Offers) enabled, Then additional information is received:
- Notification Posting: As soon as a revenue event tied to the LoyaltyBoost offer is recorded, a notification is promptly sent to your postback URL. This occurs in the form of a POSTrequest.
The system expects a 200 - OK response from the postback URL. If this response is not received, the system retries four more times, with delays of 60s, 90s, 120s, and 150s between each subsequent attempt.
There are two methods to process events sent to the postback URL:
Macros are supported in the postback URL and can be used to receive relevant payload attributes in the URL itself without having to parse the request body.
- The {payout} macro represents the amount earned (in USD) from a conversion/click event on an offer.
- Any postback parameters are available as macros. For instance, a payload attribute like user_idis accessible in the postback URL as {user_id}.
When using the POST method, the configured postback URL will receive a JSON object in the body of the POST request. This object contains the following attributes:
Attribute | Description |
offer_id | The ID associated with the offer event. |
payload | Data provided when serving offers. |
payout | The amount earned from conversion/click event on an Offer (in USD). |
timestamp | The timestamp when the conversion was received by our tracking system (in ISO 8601 format). |
advertiser_name | The name of the offer advertiser. |
is_loyaltyboost | Indicates whether the offer was LoyaltyBoost enabled, set to "1" if true. |
In the following example, two payload attributes (confirmationref and user_id) were passed when serving the offer. You can include any number of payload attributes to be returned in the postback response.
When a postback is sent to your postback URL for a LoyaltyBoost offer, the payload structure remains the same as for non-LoyaltyBoost offer events, except for the "is_loyaltyboost" attribute, which will be returned as "1". In this scenario, you'll need to examine the child "payload" object to find an attribute passed into the tracking link that identifies the user you intend to reward.
📢 If you're running into any issues while going through the integration process, feel free to contact us at [email protected].