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 MomentScience 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
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.
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.
There are three 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.
Another method to handle postback events is through the GET method. With this approach, the postback URL can receive parameters directly appended to the URL itself. These parameters contain all relevant information about the event, such as offer ID, payout, timestamp, advertiser name, and more. The URL structure allows for easy retrieval and parsing of event data without the need for a request body.
In this example URL:
- payout: Represents the amount earned (in USD) from a conversion/click event on an offer.
- timestamp: Indicates the timestamp when the conversion was received by the tracking system (in ISO 8601 format).
- offer_id: Refers to the ID associated with the Offer event.
- advertiser_name: Specifies the name of the Offer advertiser.
- is_loyaltyboost: Indicates whether the Offer was LoyaltyBoost enabled, with a value of "0" for false and "1" for true.
- confirmationref and user_id: Other payload attributes passed when serving the Offer, accessible directly in the URL for easy retrieval.
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]