Step 1: Create an endpoint on your server
To ensure that users receive their virtual currency or premium service after successfully completing an offer or payment, you must create an endpoint on your server that we can request to notify you of the user reward. Once you receive the notification, it is up to you to deliver that reward to the user.
Our system expects an
HTTP 200 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, refer to the advanced configuration section on implementing a server-side callback.
Callback Structure and Behavior
We call your endpoint with an
HTTP GET request. When we request your endpoint, we add in several parameters.
||Always||The ID of the user to be credited|
||Always||The request signature, which you must verify to ensure the request's authenticity.
||Always||The amount of virtual currency the user is credited|
||Always||The name of the virtual currency being rewarded as it appears in the Fyber dashboard|
||Always||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|
||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 are passed back, completely unchanged, in the reward callback|
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 allows you to verify that the callback came from Fyber.
Step 2: 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 to receive callback requests.
The IP ranges and addresses that you must whitelist are provided below.
|Fyber IP Address|
Step 3: Implement your response
Fyber's server decides whether the callback request was successful based on the HTTP status code of your response.
|Callback Request Type||Description|
|Response||A successful callback must return a blank HTTP 200 status code. This indicates to our servers that you have successfully processed the callback. Any other response is interpreted as an Unsuccessful callback (see below).|
|[Redirects]||Fyber’s servers follow HTTP redirects (status code 301 / 302), however, all redirect locations must be absolute URLs, as specified in the W3C standard|
|Unsuccessful Callbacks||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 causes 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
Step 4: Configuring 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.
Fyber automatically adds in the parameters necessary for you to deliver the reward to the user, so you only need to configure the endpoint itself.
Security token you find in the dashboard should never be placed in your client-side integration. This token 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 you ever feel your token has been compromised, change it in the dashboard and then update your server-side configurations with the new token.
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 ensure that you never incorrectly reward a user twice. We recommend storing all transaction IDs in your system and comparing your known list to the id sent in each reward callback.
Security token is generated for you to use when calculating the
sid parameter. You can change this token at any time, if necessary.
You can 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
Best Practice Check
Due to the universally unique nature of the Transaction ID, adding the ID to your callback ensures 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.
Below is an example code showing 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. require File.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 dashboard get '/reward' do begin #### PARAMETERS #### # Gather the parameters that will be used when calculated the sid and for crediting the reward user_id = params['uid'] amount = params['amount'] # 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 line trans_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 lines pub0 = params['pub0'] pub1 = params['pub1'] # Gather the additional parameters not used for the sid but still used rewarding currency_name = params['currency_name'] currency_id = params['currency_id'] #### SID #### # Calculate the sid from the callback parameters sid_string = '' sid_string += $SECURITY_TOKEN sid_string += user_id sid_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 lines sid_string += trans_id sid_string += pub0 sid_string += pub1 sid = Digest::SHA1.hexdigest sid_string #### PROCESSING #### # Make sure the sid parameter matches what's in the callback if (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 transactions if !(get_transactions(uid).include? trans_id) # Reward the user # For this example we assume that reward_user credits the user with the reward amount reward_user(uid, amount, pub0, pub1, currency_name) # Set the status to 200 so that Fyber knows the callback was processed status 200 body '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 processed status 200 body 'Duplicate transaction id. Callback rejected.' end else # If the sid is incorrect, you can safely ignore the callback # Set the status to 200 so that Fyber knows the callback was processed status 200 body 'Bad sid. Callback rejected.' end rescue Exception => 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 processed status 500 body 'Callback failed. Error: ' + e.message end end
Under your Reward Handling configuration in the dashboard, you can 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 send a callback to your configured
Callback URL in the same way that we do for an actual user reward.
Testing Serverside Callbacks in the Dashboard
Custom parameters (
pub9) are included in the callback since they must be sent along from your integration in the request.
You have now successfully set up rewards using Server-Side Callbacks.