Handling Postback Events

overview postbacks are server to server (s2s) notifications that momentscience sends to your system whenever a user interacts with an offer and generates a conversion or revenue event they allow your backend to automatically track conversions, credit users, process payouts, and synchronize reporting without any manual intervention how postbacks work postbacks enable momentscience to notify your server whenever a user completes an offer, earns a reward, or generates revenue this happens via a get or post request sent to your configured postback url user interaction a user clicks an offer in your app or website event tracking momentscience records the click and monitors completion conversion completion the user completes the offer successfully postback triggered momentscience sends a get or post request to your server server processing your server parses the postback payload updates your internal systems (e g , rewards, payouts, analytics) acknowledgment your server responds with http 200 ok success logging momentscience marks the postback as successfully delivered sequencediagram participant user as user participant app as your app participant ms as momentscience participant server as your server user >>app clicks an offer app >>ms sends offer request ms >>app returns offer content user >>app completes conversion ms >>server sends postback request (get/post) server >>ms responds with 200 ok server >>app updates user rewards why use postbacks postbacks are essential for real time tracking, automated rewards, and accurate reporting they allow your system to stay synchronized with momentscience whenever a user completes an offer or generates revenue benefit what it means example real time event tracking receive instant updates when a conversion or payout occurs credit loyalty points instantly after offer completion automated user rewards automatically credit users with points, cashback, or perks add cashback to a user's wallet right after conversion seamless data syncing keep your system aligned with momentscience attribution data align revenue numbers in your bi dashboards simplified reporting eliminate manual reconciliation between systems double reward points for specific campaigns flexible integration choose between get, post, or macro based urls send conversion data to tools like salesforce, amplitude, or appsflyer how postbacks help track revenue from offer clicks and conversions credit users for completed offers automatically automate loyaltyboost multipliers and rewards keep your systems fully synchronized without manual processing configure your postback url setting up postbacks involves two main steps create a server endpoint to receive postback notifications configure your postback url in the momentscience dashboard step 1 create a server endpoint your server must have an endpoint that accepts incoming postbacks and processes them reliably requirements accept get or post requests, depending on your integration preference returns an http 200 ok status code upon successful receipt processes the received data asynchronously (recommended) log all incoming requests, for debugging and reconciliation handles the data formats described later in this guide example endpoint path https //api yourcompany com/momentscience/postbacks step 2 configure postback url in dashboard after creating your endpoint, you must register it in the 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 go to tools > postback explorer click test endpoint momentscience will send a sample postback to your server check your server logs to verify that the request is received successfully your system returns http 200 ok receiving postback data momentscience supports two methods for sending postbacks to your server get sends data as url query parameters post sends data as a structured json body (recommended) choose the method that best fits your integration option a using get method with the get method, momentscience sends event data as url query parameters your endpoint receives a request where all postback fields are included in the query string suitable for lightweight integrations where you only need simple key value pairs 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 when to use get for quick integrations where you want simple url based parameters when working with legacy systems that only accept get be cautious if your data payloads are large, since url length has limits option b using post method (recommended) with the post method, momentscience sends a structured json payload in the request body this is the recommended integration approach for most implementations your endpoint receives a json object containing all postback fields ideal when you need nested payloads, secure data handling, and better validation example post request { "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" } when to use post when you need structured data and nested objects for better security since data is not exposed in the url recommended for modern integrations and most server frameworks postback data fields when a user engages with an offer or completes a conversion, momentscience sends a postback request to your configured server endpoint the request includes structured data that helps you credit user rewards track conversions reconcile payouts update reporting dashboards supported postback fields attribute description offer id unique identifier for the offer advertiser name name of the advertiser providing the offer payout revenue earned from the conversion, in usd timestamp iso 8601 timestamp 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 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 customizing get postbacks with macros if you’re using the get method for receiving postbacks, you can dynamically insert values into your postback url using macros these macros are placeholders that momentscience automatically replaces with real event data before sending the postback macros are dynamic variables enclosed in { } at runtime, momentscience replaces each macro with the actual event value this allows you to customize your endpoint url to include specific user and offer information template url https //api example com/postbacks?payout={payout}\&user id={user id}\&offer id={offer id} actual request sent by momentscience https //api yourcompany com/postbacks?payout=2 10\&user id=3410444\&offer id=1511 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 retry behavior momentscience ensures reliable delivery of all postbacks to your server whenever your endpoint fails to respond with http 200 ok, the system automatically retries the request using an incremental backoff strategy how retries work when momentscience sends a postback, your server must return an http 200 ok response if your server responds with 200 ok → the postback is marked as successful does not respond or returns an error → the postback enters a retry queue momentscience retries up to 5 times for each failed postback if all retries fail, the event is marked as permanently failed 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 viewing postback history the postback explorer in the momentscience dashboard allows you to manage postback settings, view historical data, and download reports for auditing and debugging use this feature to track delivery status, troubleshoot failed postbacks, and confirm that your integration is working as expected open the postback explorer log in to the momentscience dashboard in the sidebar, click tools select postbacks & webhooks from the menu scroll to the postback history section below the settings panel, you’ll find the postback history table this table shows event timestamps offer ids and advertiser names payout amounts delivery status (success or failed) http response codes from your server filter by date range click the date range selector choose from and to dates manually or use the shortcuts menu to quickly select a preset range (e g , “last 7 days,” “this month”) click save changes to apply the filter refresh the data to see the latest postback events, click the refresh button above the history table export the history click download csv to export the filtered data the csv file includes all event details for reconciliation, debugging, or external reporting if you encounter issues with your postback implementation, feel free to contact us at help\@momentscience com