Server-Side Rewarding

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.

Callback Structure and Behavior

We call your endpoint with an HTTP GET request. When we request your endpoint, we add in several parameters.

Parameter Added Automatically Details
uid Always The ID of the user to be credited
sid Only if security_token is set 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 + …)
amount Always The amount of virtual currency the user should be credited
currency_name Always The name of the virtual currency being rewarded as it appears in the DT dashboard
currency_id Always The ID of the virtual currency being rewarded as it appears in the DT dashboard
_trans_id_ 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 are passed back, completely unchanged, in the reward callback
offer_title Only if configured in the dashboard Encoded offer title
payout_net Only if configured in the dashboard  
net_payout_eur Only if configured in the dashboard  
payout_gross Only if configured in the dashboard  
payout_currency Only if configured in the dashboard  
lpid Only if configured in the dashboard  Landing page ID, ID of the Offer
vcs_enabled Only if configured in the dashboard Whether VCS was enabled when the click happened - True or False
placement_id/span>
Only if configured in the dashboard  

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 DT.

Step 2: Whitelist DT IPs

If your server has restrictive security settings and/or is protected by a firewall, you may have to unblock DTs servers’ IP addresses to receive callback requests.

The IP ranges and addresses that you must whitelist are provided below.

DT IP Address
52.51.229.163
52.208.7.124
52.212.4.99
35.196.16.124
34.23.227.47
34.139.250.247
34.139.143.157
35.227.32.40
104.196.193.31
35.185.30.237
34.139.252.26
34.138.146.173
104.196.100.128

Step 3: Implement Your Response

DT'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] DT'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 _trans_id_, or if you choose to reject the callback intentionally, we recommend you send a HTTP 200 status code response. In this way, you indicate to us that the callback was processed and we do not resend it.

Step 4: Configuring Your Endpoint in the DT Dashboard

Once you have configured your endpoint, you can configure that endpoint in the Callback URL under Reward Handling in Settings tab of the DT Dashboard.

Screen Shot 2023-02-15 at 11.21.23.png

DT 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 Alert

The 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 DT'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 ?parameter=value&_trans_id_=.

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 fraudulently misuse your system into providing unearned rewards.

Code Example

Below is an example code showing how to calculate the sid and process the callback.

Ruby
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

 

Testing Callbacks

Click Screen Shot 2023-02-15 at 11.25.36.pngand a Test Server-side Callback window appears 

By entering a reward amount and selecting a virtual currency, you can have our system configure a reward callback for you.

Test Server-side Callback.mov-high.gif

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. 

Custom parameters (pub0 ... 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.

Back to Top ⇧