Handling Postback Events

overview postbacks are server to server notifications that momentscience sends to your system when users interact with offers and generate revenue this guide shows you how to set up, receive, and process these notifications in this guide, you'll learn how to configure your postback url in the momentscience dashboard receive and handle postback data using the get, post, or macro url method interpret key postback fields and ensure successful event processing why use postbacks postbacks enable critical functionality for your integration track revenue from offer clicks and conversions credit users for completed offers automate rewards for loyaltyboost engagements sync conversion data with attribution, analytics, or crm platforms configure your postback url postback setup involves two parts creating a receiver endpoint on your server, and configuring it in the momentscience dashboard step 1 create a server endpoint create an endpoint on your server that accepts get or post requests returns an http 200 ok status code upon successful receipt processes the received data asynchronously (recommended) handles the data formats described later in this guide example endpoint path https //api yourcompany com/momentscience/postbacks step 2 configure in momentscience dashboard log in to your momentscience dashboard navigate to tools > postback explorer choose your desired http method ( get , post ) enter your postback url click save you can also use the "test endpoint" button to verify your server setup with a sample postback retry behavior if your endpoint fails to return a 200 ok response, momentscience automatically retries the postback attempt delay description 1 0s initial attempt 2 60s first retry, one minute after failure 3 90s second retry 4 120s third retry 5 150s final retry attempt after 5 failed attempts, the postback is marked as failed and will not be retried again monitor your server logs to detect any missed postbacks what data is included in a postback when an event occurs, momentscience sends the following data to your configured postback url attribute description offer id unique id of the offer advertiser name name of the advertiser payout revenue earned from the conversion or click event (usd) timestamp iso 8601 timestamp of when the conversion was recorded payload any custom data passed when serving the offer (e g , pub user id , session info) is loyaltyboost "1" if the offer is a loyaltyboost offer, "0" otherwise receiving postback data you can receive postback data using either get or post choose the method that fits your system’s requirements option a get method with url parameters momentscience sends a get request to your endpoint with event fields included as query parameters example request https //api example com/postbacks?payout=2 10\&timestamp=2023 09 20t15 27 40 802z\&offer id=1511\&advertiser name=momentscience\&is loyaltyboost=0\&user id=3410444 this method works well when you want simple access to parameters without body parsing your server has url length limitations (be cautious with large payloads) you're integrating with legacy systems that expect get requests option b post method with json body momentscience sends a post request to your endpoint with the postback data in a structured json payload how it works momentscience sends a post request to your endpoint with a json body containing all relevant data { "offer id" "1511", "advertiser name" "momentscience", "payout" "2 10", "payload" { "user id" "3410444", "session id" "a90310222" }, "timestamp" "2023 09 20t15 27 40 802z", "is loyaltyboost" "0" } this method is ideal when you need to process complex or nested data your backend framework has good json parsing capabilities you prefer a structured data format customizing get postbacks with macros if you're using the get method, you can dynamically inject values using macros in the url https //api example com/postbacks?payout={payout}\&user id={user id}\&offer id={offer id} during runtime, macros like {user id} or {payout} will be replaced with actual values from the postback event supported macros macro description example value {payout} revenue amount (usd) 2 10 {timestamp} iso 8601 timestamp 2023 09 20t15 27 40 802z {offer id} offer id 1511 {advertiser name} advertiser name momentscience {is loyaltyboost} "1" for loyaltyboost, "0" otherwise 0 {any payload key} custom payload values (e g , {user id} ) 3410444 handling loyaltyboost offers 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 to reward users detect loyaltyboost offers ( is loyaltyboost = "1") extract the user identifier from payload (e g , user id) convert payout value to your internal reward system (e g , points or credits) credit the user's account record the reward transaction if you use macros, {is loyaltyboost} can help you distinguish loyaltyboost events directly in your url if you encounter issues with your postback implementation, feel free to contact us at help\@momentscience com