Server-Side Callbacks

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

Parameter Added Automatically Details
uid Always The ID of the user to be credited.
sid Always 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 Fyber dashboard.
currency_id Always The id of the virtual currency being rewarded as it appears in the Fyber 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 will be passed back, completely unchanged, in the reward callback.
payout_net Optional The net payout the publisher receives for this transaction (in USD)
vcs_enabled Optional 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 Description
146.0.239.0/24 146.0.239.0/24/24 is a subnet mask. You need to whitelist multiple IP addresses.

For example: from 146.0.239.0 to 146.0.239.255.
85.195.83.44  
52.51.229.163  
52.208.7.124  
52.212.4.99  

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 Description
Response 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).
Redirects 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.
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 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.

Code Example

Below you will find some example code that shows 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
 

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.

Security token is generated for you to use when calculating the sid parameter. You may choose to change this token at any time.

Security Alert

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.

106ec5f-with_transid__1_.png

Testing Callbacks

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.

Note

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.