Overview
The reward validation callback feature is used to determine whether or not Friendbuy should fulfill the reward for a conversion based on logic in your own system, such as returns or cancellations. This is meant to provide flexibility on top of the fraud checks and reward criteria that Friendbuy provides.
Note, it is best used with a reward days to delay, set in Reward Configuration, which is a delay to postpone the processing of a reward until a specified amount of time has passed.
Example Use Case
Acme has a widget and has set up a reward validation callback and a reward delay of 10 days. Alice shares with Bob through the widget on Acme's website. Bob clicks on the link and makes a purchase from Acme, which generates a conversion and a reward. Since Acme has a reward delay of 10 days, the reward will not be processed until the 10th day. Bob cancels his order 4 days after making the purchase which lead to the conversion. On the 10th day, while processing the reward, Friendbuy fires the reward validation callback. Acme's system receives the request and responds indicating that the reward should not be fulfilled.
How it Works
When validating a reward, we will make an HTTP POST request to the url provided in the Validation URL configuration of Reward Criteria. The HTTP response code returned by your system will indicate if the reward should be fulfilled or not. A response code between 200 and 299 will validate the reward, any other response code will invalidate the reward. If you are using a reward delay, we will make the request after the reward delay expires.
The request body will include details about the purchase that generated the conversion, such as referrer, purchase date, order id, and more. The full data included is described in our REST API documentation under the conversions and conversion detail sections.
How to Configure
Create an endpoint or route on your platform that will be used to accept the HTTP POST from Friendbuy. The endpoint must be HTTPS and must be accessible to Friendbuy's system.
Log in to Friendbuy
Navigate to the widget you want to add the reward validation callback to.
Click "edit" to open the widget builder
Click the "Edit" button under Reward > Criteria
6. From the Reward Criteria menu, select "Validation URL" and click "add"
7. Enter the URL for the route you have set up to process the reward validation callback and hit save.
Security
The POST requests made to the Validation Callback URL include a signature header, X-FRIENDBUY-SIGNATURE-V2, that you can use to verify that the request has come from Friendbuy. Note, any other header signatures included in the request should be ignored.
You can follow these steps to verify the request:
Use the JSON post body (as a string) and your API secret* to compose an HMAC-SHA1 value as follows: HMAC(api_secret, post_data)
Base64-encode the resulting hash value from above
Compare the Base64-encoded hash value to the X-FRIENDBUY-SIGNATURE-V2 header value
If the values match, then the request has been authenticated.
* Your API secret may be found under "Settings -> Configurations -> API Access"
Here is an example of the signature creation algorithm implemented in Python:
from base64 import b64encode
from hashlib import sha1
import hmac
import urllib
def create_signature(api_secret, data):
"""
Given the data for the request as a string, create an
HMAC-SHA1 composition of the data and the API secret.
"""
mac = hmac.new(
api_secret.encode("utf-8"),
data.encode("utf-8"), sha1
)
computed = b64encode(mac.digest())
return computed.strip()
If you'd like to restrict access only to the servers Friendbuy sends these requests from, you can whitelist the following IP addresses:
50.18.183.9
50.18.110.159
35.153.4.211