To ensure that users receive their virtual currency or premium service after successfully completing an offer or payment, you need to create an endpoint on your server that we can request in order to notify you of the user reward. Once you receive the notification, it will be up to you to deliver that reward to the user.
Our system expects an HTTP200 response to indicate that you have successfully processed the callback. All other HTTP response codes indicate a failure. For more information on setting up your endpoint, please refer to the advanced configuration section on implementing a server-side callback.
Callback Structure and Behavior
We will call your endpoint with an HTTP GET request. When we request your endpoint, we will add in several parameters.
The ID of the user to be credited.
The request signature, which you should verify to ensure the request's authenticity.
The sid is computed as a SHA1 hash of the request parameters: sid = sha1(security_token + user_id + amount + _trans_id_ + pub0 + pub1 + pub2 + …)
The amount of virtual currency the user should be credited.
The name of the virtual currency being rewarded as it appears in the Fyber dashboard.
The id of the virtual currency being rewarded as it appears in the Fyber dashboard.
Only if configured in the dashboard
The unique transaction ID in the form of a UUID (“Universally Unique Identifier”). Use this to check whether the transaction has already been processed in your system.
pub0 - pub9
Only if added in the API request
It is possible to add custom parameters (called pub0, pub1, ... , pub9) to your API request for offers. These parameters will be passed back, completely unchanged, in the reward callback.
The net payout the publisher receives for this transaction (in USD)
A flag specifying whether the conversion came from a VCS (value=true) or not (value=false)
Best Practice Check
To ensure the security of your reward callbacks, we recommend that you calculate the sid parameter and compare it to the parameter sent in the callback. This will allow you to verify that the callback came from us.
STEP 1: Whitelist Fyber IPs
If your server has restrictive security settings and/or is protected by a firewall, you may have to unblock Fyber’s servers’ IP addresses in order to receive callback requests.
The IP ranges and addresses that you need to whitelist are given below.
Fyber IP Address
188.8.131.52/24, /24 is a subnet mask. You need to whitelist multiple IP addresses.
For example: from 184.108.40.206 to 220.127.116.11.
STEP 2: Implement your Response
Fyber's server will decide whether the callback request was successful based on the HTTP status code of your response:
Callback Request Type
A successful callback needs to return a blank HTTP 200 status code. This indicates to our servers that you have successfully processed the callback. Any other response will be interpreted as an Unsuccessful callback (see below).
Fyber’s servers will follow HTTP redirects (status code 301 / 302), however, all redirect locations must be absolute URLs, as specified in the W3C standard.
If an error occurs on your side, you may send any status code other than HTTP 200 to indicate to our servers that the callback was not processed successfully.
Any response other than HTTP 200 will cause our system to resend the callback up to 10 additional times with an exponentially increasing delay between each attempt
Duplicates and Rejected callbacks
If you identify the callback request as a duplicate based on the _trans_id_, or if you choose to reject the callback intentionally, we recommend you send an HTTP 200 status code response. In this way you will indicate to us that the callback was processed and we will not resend it.
Below you will find some example code that shows how to calculate the sid and process the callback.
require'rubygems'require'bundler'require'sinatra'require'digest/sha1'# For this example we assume that you have another file with the methods necessary to credit the reward to your users.requireFile.join(File.dirname(__FILE__), 'reward_processing.rb')
# Your security token should only be present on your server and Fyber's$SECURITY_TOKEN='<YOUR SECURITY TOKEN>'#### ENDPOINT ##### Your endpoint for the reward callback should be configured in the Fyber dashboardget'/reward'dobegin#### PARAMETERS ##### Gather the parameters that will be used when calculated the sid and for crediting the rewarduser_id=params['uid']
# For this example we assume that you have activated the transaction id in the Fyber dashboard# If you have not, you can remove the following linetrans_id=params['_trans_id_']
# For this example we assume you are passing custom parameters to assist in rewarding# If you are not, you can remove the following two linespub0=params['pub0']
# Gather the additional parameters not used for the sid but still used rewardingcurrency_name=params['currency_name']
#### SID ##### Calculate the sid from the callback parameterssid_string=''sid_string+=$SECURITY_TOKENsid_string+=user_idsid_string+=amount# For this example we assume you have the trasaction id, pub0 and pub1 parameters# If you do not, you can remove the following three linessid_string+=trans_idsid_string+=pub0sid_string+=pub1sid=Digest::SHA1.hexdigestsid_string#### PROCESSING ##### Make sure the sid parameter matches what's in the callbackif (sid==params['sid'])
# Make sure you have not already processed the transaction# For this example we assume that get_transactions returns an array of credited transactionsif !get_transactions(uid).include?(trans_id)
# Reward the user# For this example we assume that reward_user credits the user with the reward amountreward_user(uid, amount, pub0, pub1, currency_name)
# Set the status to 200 so that Fyber knows the callback was processedstatus200body'Callback Successful.'else# If the transaction was already rewarded, you can safely ignore the callback# Set the status to 200 so that Fyber knows the callback was processedstatus200body'Duplicate transaction id. Callback rejected.'endelse# If the sid is incorrect, you can safely ignore the callback# Set the status to 200 so that Fyber knows the callback was processedstatus200body'Bad sid. Callback rejected.'endrescueException=>e# If you ran into any error while processing the callback, you will want Fyber to try again# Set the status to something other than 200 so that Fyber knows the reward was not processedstatus500body'Callback failed. Error: '+e.messageendend
Configure your Endpoint in the Fyber Dashboard
Once you have configured your endpoint, you can configure that endpoint in the Callback URL under Reward Handling in Settings tab of the Fyber Dashboard.
We will automatically add in the parameters necessary for you to deliver the reward to the user, so you only need to configure the endpoint itself.
Adding the Transaction ID
It is possible to uniquely identify every callback sent to your system with Fyber's Transaction ID. Checking the Transaction ID is a simple way to absolutely ensure that you never incorrectly reward a user twice. We recommend storing all Transaction IDs on your system and comparing your known list to the ID sent in each reward callback.
A Security token is generated for you to use when calculating the sid parameter. You may choose to change this token at any time.
The Security token you find in the dashboard should never be placed in your client-side integration. This is a token that should be kept secret between your servers and ours. You should ensure that there is no possible way that any of your users can access it. If ever you feel your token may have been compromised, you may change it in the dashboard and then update your server-side configurations with the new token.
You may add this parameter by including ?_trans_id_= at the end of your Callback URL in the dashboard. If you already have some parameters as part of your URL, you can include the transaction id instead by including ?parameter=value&_trans_id_=.
Best Practice Check
Due to the universally unique nature of the transaction id, adding the id to your callback will ensure that the sid parameter is also universally unique. Using these parameters together, you can add in additional security to make sure that users can not fraud your system into providing unearned rewards.
Under your Reward Handling configuration in the dashboard, you will find an option to Test Serverside Callbacks. By entering a user id, reward amount and selecting a virtual currency, you can have our system configure a reward callback for you. Once you hit the Send callback button, our servers will send a callback to your configured Callback URL in the same way that we will for an actual user reward.
Custom parameters (pub0 ... pub9) will not be included in the callback, since they must be sent along from your integration in the request. For more information, refer to our section on Custom Parameters.