Reward Validation Callback

Written by Britain Southwick Updated over a week ago

Overview

The reward validation callback feature is used to determine whether or not Friendbuy should fulfill the reward for a conversion based on your criteria, such as fraud checks, returns, or cancellations. It is best used with a reward delay (a reward delay will 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.

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