Developers

Webhooks 2.0 Overview

Webhooks are used to notify your system when certain Friendbuy events happen. You can use webhooks to record information about sharing and referrals, or perform actions in your own systems when these events happen. A common use-case is tracking sharing and conversion information in a CRM.

We love developers, and we want to help. If you have any issues, head over to support and let us know.

Create developer account

Using an older version?

Click here for Wehooks v1.0 documentation.

If you are a v1.0 consumer and would like to upgrade to v2.0, please contact your sales representative.

Webhooks

Configuring

Global Webhooks

Global Webhooks are configured at the Account level and the configurations will be applied to all triggering events uniformly regardless of each event's campaign level settings. Webhooks configured globally are:

  • Shares
  • Conversions
  • Rewards
  • Share Email Opt-outs

You may configure your account's Global Webhooks with these steps:

  • Log in to Friendbuy
  • Go to Settings
  • Go to the Webhooks tab
  • Enter the URL for the webhook

Note: The Share Webhook should not be relied upon for implementing key logic in a referral program. It is fine to use Share Webhooks to retrieve valuable data, to store analytics, or to trigger various actions. A Personal URL (PURL) will not have a Share event associated with it - because it is only a copy & paste action - hence the Reward Webhook and Conversion Webhook from a PURL will not contain a Share ID and there will be never be a Share Webhook fired for someone sharing a PURL.

Campaign Webhooks

Campaign Webhooks are configured on a campaign-by-campaign basis. The webhook will only be triggered for events configured for the related campaign. Webhooks configured at the campaign level are:

  • Custom Reward Validations

For instructions on how to configure Campaign Webhooks, please see the documentation for the desired webhook.

A note on security: Friendbuy requires SSL on all webhook URLs. To put it simply, the URLs you provide have to start with https, and your server needs to have a valid certificate. Optionally, you can provide HTTP basic authentication credentials and we will use them with webhook calls.

Event Types

Rewards

After a conversion's reward is evaluated, Friendbuy will send a POST request with a JSON body in the form of the following example to the provided URL.

Example POST Body

{
    "amount": 5.0,
    "conversion": {
      "type": "share",
      "campaign": {
        "created_at": "2016-03-22 20:05:45.074247-07:00",
        "id": 333477,
        "name": "Test Widget",
        "published": true,
        "referral_incentive": {
          "type": "reward_amount",
          "value": 5.0
        }
      },
      "created_at": "2016-04-13 16:21:26.424652-07:00",
      "detail_uri": "https://api.friendbuy.com/v1/conversions/47294",
      "fraud": {
        "fuzzy_email": true,
        "same_customer": false,
        "same_email": false,
        "same_shopper": false
      },
      "id": 47294,
      "possible_self_referral": false,
      "purchase": {
        "coupon_code": null,
        "customer": {
            "account_id": "77",
            "detail_uri": "https://api.friendbuy.com/v1/customers/3",
            "email": "recipient@example.com",
            "first_name": "Share",
            "id": "77",
            "last_name": "Recipient",
            "stripe_customer_id": " "
        },
        "date": "2016-04-13 16:21:26.424652",
        "email": "friend@example.com",
        "ip_address": "127.0.0.1",
        "new_customer": "yes",
        "coupon_code": "EXAMPLECODE"
        "order_id": "2016-04-13T16:21:26.325Z",
        "products": [],
        "total": 1337.0
      },
      "referrer": {
        "customer": {
          "account_id": "friendbuy-sharer",
          "detail_uri": "https://api.friendbuy.com/v1/customers/19486",
          "email": "sharer@example.com",
          "first_name": null,
          "id": 19486,
          "last_name": null
        },
        "email": "sharer@example.com",
        "facebook_friends_count": 0,
        "name": "",
        "twitter_followers_count": 0
      },
      "reward": null,
      "share": {
        "campaign": {
          "created_at": "2016-03-22 20:05:45.074247-07:00",
          "id": 333477,
          "name": "Test Widget",
          "published": true,
          "referral_incentive": {
            "type": "reward_amount",
            "value": 5.0
          }
        },
        "created_at": "2016-04-13 16:19:37.972390-07:00",
        "detail_uri": "https://api.friendbuy.com/v1/shares/139986",
        "id": 139986,
        "ip_address": "127.0.0.1",
        "message": {
          "content": "testing a share",
          "network": "email"
        },
        "email_recipients": ["friend@example.com"],
        "sharer": {
          "customer": {
            "account_id": "friendbuy-sharer",
            "detail_uri": "https://api.friendbuy.com/v1/customers/19486",
            "email": "sharer@example.com",
            "first_name": null,
            "id": 19486,
            "last_name": null
          },
          "email": "sharer@example.com",
          "facebook_friends_count": 0,
          "name": "",
          "twitter_followers_count": 0
        }
      },
      "status": "unmarked"
    },
    "created_at": "2016-04-13 16:21:27.137658-07:00",
    "evaluate_at": null,
    "id": 16501,
    "rejected_reasons": null,
    "status": "valid",
    "type": "fixed_cash"
}

JSON Field Descriptions

Field Description
id The Friendbuy id of this reward
amount The amount of the reward[].type to be given for a valid conversion
created_at Date and time this reward
evaluate_at Date and time this conversion's validity was evaluated
type The unit of the reward to be granted for a valid conversion
status valid, or invalid depending if this reward passed defined validation checks.
rejected_reasons A JSON object with fields matching those of the conversion.fraud object. Values are human-readable descriptions that this conversion has been flagged with them. Only fraud fields with a true will be present.
conversion.id Unique identifier for the conversion corresponding to this reward.
conversion.type The type (source) of the conversion, one of share, customer_personal_url, email_personal_url, or reminder_email.
conversion.created_at Date and time of conversion
conversion.detail_uri The Friendbuy REST API resource for this conversion
conversion.possible_self_referral true or false indicating that the shopper may have self referred.
conversion.reward Deprecated. Always None
conversion.status The status of the conversion
conversion.campaign.id Unique identifier for the campaign associated with the conversion
conversion.campaign.name Name for the campaign associated with the conversion
conversion.campaign.published Whether the campaign for this conversion had been published. Expected to be true
conversion.campaign.referral_incentive.type The unit of the reward to be granted for a valid conversion
conversion.campaign.referral_incentive.value The amount of the reward_type to be given for a valid conversion
conversion.fraud.fuzzy_email true or false depending on if there is a fuzzy match between the referrer and the purchaser's email address
conversion.fraud.same_customer true or false depending on if there is a match between the referrer and the purchaser
conversion.fraud.same_email true or false depending on if there is a match between the referrer and the purchaser's email address
conversion.fraud.same_shopoper true or false depending on if there is a match between the referrer and the purchaser's browser
conversion.purchase.coupon_code A coupon code used with the purchase
conversion.purchase.customer.account_id The ID for the purchasing customer that was passed into a SmartPixel or REST API call
conversion.purchase.customer.detail_uri The Friendbuy REST API resource for the purchasing customer
conversion.purchase.customer.email The purchasing customer's email address
conversion.purchase.customer.first_name The purchasing customer's first name
conversion.purchase.customer.last_name The purchasing customer's last name
conversion.purchase.customer.id The Friendbuy REST API resource for the purchasing customer
conversion.purchase.customer.stripe_customer_id The purchasing customer's Stripe customer ID (always shown but empty unless passed in through a REST API call or the SmartPixel)
conversion.purchase.date The date and time of the purchase causing this conversion
conversion.purchase.email The e-mail address of the purchasre if collected
conversion.purchase.ip_address The ip address of the pruchaser.
conversion.purchase.new_customer Whether or not the new order was made by a new customer, as passed into the conversion tracker.
conversion.purchase.order_id The order id of this purchase as passed in to the conversion tracker.
conversion.purchase.products A list of the produts that were purchased, as passed in to the conversion tracker.
conversion.purchase.total The total sum of the purchase causing this conversion, as passed in to the conversion tracker.
conversion.referrer.email Email address of the person who referred this conversion
Only present if a valid email address was collected
conversion.referrer.facebook_friends_count How many facebook friends this referrer has
conversion.referrer.name The title of the referrer, if given.
conversion.referrer.twitter_followers_count How many Twitter followers this referrer has
conversion.referrer.customer.id Friendbuy ID for the customer associated with the share
Only present when a customer id is passed via JavaScript
conversion.referrer.customer.detail_uri The Friendbuy REST API resource for the customer who originated this share.
conversion.referrer.customer.email Email for the customer associated with the share
Only present when a customer email is passed via JavaScript
conversion.referrer.customer.first_name The first name of the sharing customer, if given.
conversion.referrer.customer.last_name The last name of the sharing customer, if given.
conversion.reminder_email.id If this conversion came from a reminder email, the unique identifier for the reminder email
conversion.reminder_email.referral_code The referral code of the reminder email
conversion.reminder_email.created_at The date and time that the reminder email was created
conversion.reminder_email.campaign Information about the campaign for which the reminder email was generated
conversion.reminder_email.share Information about the share for which the reminder email was generated
conversion.share.id If this conversion came from a share, the unique identifier for the share
conversion.share.created_at Date and time of share
conversion.share.detail_uri The Friendbuy REST API resource for this share.
conversion.share.email Email address of the person who shared
Only present if a valid email address was collected
conversion.share.facebook_friends_count How many facebook friends this sharer has
conversion.share.name The full name of the sharer, if given.
conversion.share.ip_address User IP address at the time of sharing
conversion.share.twitter_followers_count How many Twitter followers this sharer has
conversion.share.message.content The Message content
conversion.share.message.network Network the share was distributed on.
conversion.share.campaign.id Unique identifier for the campaign associated with the share
conversion.share.campaign.name Name for the campaign associated with the share
conversion.share.campaign.published Whether the campaign for this share had been published. Expected to be true
conversion.share.campaign.referral_incentive.type The unit of the reward to be granted for a valid conversion
conversion.share.campaign.referral_incentive.value The amount of the reward_type to be given for a valid conversion
conversion.share.email_recipients A string representing of a JSON list of e-mail addresses this share was distributed to.
Only present if access to this field has been enabled for your account.
conversion.share.sharer.customer.id Friendbuy ID for the customer associated with the share
Only present when a customer id is passed via JavaScript
conversion.share.sharer.customer.detail_uri The Friendbuy REST API resource for the customer who originated this share.
conversion.share.sharer.customer.email Email for the customer associated with the share
Only present when a customer email is passed via JavaScript
conversion.share.sharer.customer.first_name The first name of the sharing customer, if given.
conversion.share.sharer.customer.last_name The last name of the sharing customer, if given.

Conversions

After a successful conversion, Friendbuy will send a POST request with a JSON body in the form of the following example to the provided URL.

Example POST Body

{
    "campaign": {
      "created_at": "2016-03-22 20:05:45.074247-07:00",
      "id": 333477,
      "name": "Widget Title",
      "published": true,
      "referral_incentive": {
        "type": "reward_amount",
        "value": 5.0
      }
    },
    "created_at": "2016-04-04 23:21:04.145113-07:00",
    "detail_uri": "https://api.friendbuy.com/v1/conversions/43879",
    "fraud": {
      "fuzzy_email": true,
      "same_customer": false,
      "same_email": false,
      "same_shopper": true
    },
    "id": 43879,
    "possible_self_referral": true,
    "purchase": {
      "coupon_code": null,
      "customer": {
          "account_id": "77",
          "detail_uri": "https://api.friendbuy.com/v1/customers/3",
          "email": "recipient@example.com",
          "first_name": "Share",
          "id": "77",
          "last_name": "Recipient",
          "stripe_customer_id": " "
      },
      "date": "2016-04-04 23:21:04.145113",
      "email": "friend@example.com",
      "ip_address": "127.0.0.1",
      "new_customer": "yes",
      "coupon_code": "EXAMPLECODE"
      "order_id": "2016-04-04T23:21:03.910Z",
      "products": [],
      "total": 1337.0
    },
    "referrer": {
      "customer": {
        "account_id": "friendbuy-sharer",
        "detail_uri": "https://api.friendbuy.com/v1/customers/19486",
        "email": "sharer@example.com",
        "first_name": null,
        "id": 19486,
        "last_name": null
      },
      "email": "sharer@example.com",
      "facebook_friends_count": 0,
      "name": "",
      "twitter_followers_count": 0
    },
    "reward": null,
    "rewards": [
      {
        "amount": 5.0,
        "created_at": "2016-04-04 23:21:04.897591-07:00",
        "evaluate_at": null,
        "id": 13470,
        "rejected_reasons": {
          "same_shopper": "same cookie detected"
        },
        "status": "valid",
        "type": "fixed_cash"
      }
    ],
    "share": {
      "campaign": {
        "created_at": "2016-03-22 20:05:45.074247-07:00",
        "id": 333477,
        "name": "Widget Title",
        "published": true,
        "referral_incentive": {
          "type": "reward_amount",
          "value": 5.0
        }
      },
      "created_at": "2016-03-30 23:49:35.006194-07:00",
      "detail_uri": "https://api.friendbuy.com/v1/shares/130493",
      "referral_code": "aA",
      "id": 130493,
      "ip_address": "127.0.0.1",
      "message": {
        "content": "testing",
        "network": "email"
      },
      "email_recipients": ["friend@example.com"],
      "sharer": {
        "customer": {
          "account_id": "friendbuy-sharer",
          "detail_uri": "https://api.friendbuy.com/v1/customers/19486",
          "email": "sharer@example.com",
          "first_name": null,
          "id": 19486,
          "last_name": null
        },
        "newsletter_opt_in": true,
        "send_reminder": true,
        "email": "sharer@example.com",
        "facebook_friends_count": 0,
        "name": "",
        "twitter_followers_count": 0
      }
    },
    "status": "unmarked",
    "type": "share"
}
        

JSON Field Descriptions

Field Description
id Unique identifier for the conversion
created_at Date and time of conversion
detail_uri The Friendbuy REST API resource for this conversion
possible_self_referral true or false indicating that the shopper may have self referred.
reward Deprecated. Always None
status The status of the conversion
type The type (source) of the conversion, one of share, customer_personal_url, email_personal_url, or reminder_email.
campaign.id Unique identifier for the campaign associated with the conversion
campaign.name Name for the campaign associated with the conversion
campaign.published Whether the campaign for this conversion had been published. Expected to be true
campaign.referral_incentive.type The unit of the reward to be granted for a valid conversion
campaign.referral_incentive.value The amount of the reward_type to be given for a valid conversion
fraud.fuzzy_email true or false depending on if there is a fuzzy match between the referrer and the purchaser's email address
fraud.same_customer true or false depending on if there is a match between the referrer and the purchaser
fraud.same_email true or false depending on if there is a match between the referrer and the purchaser's email address
fraud.same_shopoper true or false depending on if there is a match between the referrer and the purchaser's browser
newsletter_opt_in true if the sharer wants to be added to your newsletter mailing list.
purchase.coupon_code A coupon code used with the purchase
purchase.customer.account_id The ID for the purchasing customer that was passed into a SmartPixel or REST API call
purchase.customer.detail_uri The Friendbuy REST API resource for the purchasing customer
purchase.customer.email The purchasing customer's email address
purchase.customer.first_name The purchasing customer's first name
purchase.customer.last_name The purchasing customer's last name
purchase.customer.id The Friendbuy REST API resource for the purchasing customer
purchase.customer.stripe_customer_id The purchasing customer's Stripe customer ID (always shown but empty unless passed in through a REST API call or the SmartPixel)
purchase.date The date and time of the purchase causing this conversion
purchase.email The e-mail address of the purchasre if collected
purchase.ip_address The ip address of the pruchaser.
purchase.new_customer Whether or not the new order was made by a new customer, as passed into the conversion tracker.
purchase.order_id The order id of this purchase as passed in to the conversion tracker.
purchase.products A list of the produts that were purchased, as passed in to the conversion tracker.
purchase.total The total sum of the purchase causing this conversion, as passed in to the conversion tracker.
rewards[].id The Friendbuy id of this reward
rewards[].amount The amount of the reward[].type to be given for a valid conversion
rewards[].created_at Date and time this reward
rewards[].evaluate_at Date and time this conversion's validity will be evaluated, and a reward issued if it is valid.
rewards[].type The unit of the reward to be granted for a valid conversion
rewards[].status valid, pending, or invalid depending on if the evaluate_at time has passed and the result of the conversion's validity check
rewards[].rejected_reasons A JSON object with fields matching those of the fraud object. Values are human-readable descriptions that this conversion has been flagged with them. Only fraud fields with a true will be present.
referrer.email Email address of the person who referred this conversion
Only present if a valid email address was collected
referrer.facebook_friends_count How many facebook friends this referrer has
referrer.name The title of the referrer, if given.
referrer.twitter_followers_count How many Twitter followers this referrer has
referrer.customer.id Friendbuy ID for the customer associated with the share
Only present when a customer id is passed via JavaScript
referrer.customer.detail_uri The Friendbuy REST API resource for the customer who originated this share.
referrer.customer.email Email for the customer associated with the share
Only present when a customer email is passed via JavaScript
referrer.customer.first_name The first name of the sharing customer, if given.
referrer.customer.last_name The last name of the sharing customer, if given.
send_reminder true if the sharer would like a reminder sent if their friend has not made a purchase after 3 days.
reminder_email.id If this conversion came from a reminder email, the unique identifier for the reminder email
reminder_email.referral_code The referral code of the reminder email
reminder_email.created_at The date and time that the reminder email was created
reminder_email.campaign Information about the campaign for which the reminder email was generated
reminder_email.share Information about the share for which the reminder email was generated
share.id If this conversion came from a share, the unique identifier for the share
share.referral_code String of characters used to attribute referral events to an advocate
share.created_at Date and time of share
share.detail_uri The Friendbuy REST API resource for this share.
share.email Email address of the person who shared
Only present if a valid email address was collected
share.facebook_friends_count How many facebook friends this sharer has
share.name The full name of the sharer, if given.
share.ip_address User IP address at the time of sharing
share.twitter_followers_count How many Twitter followers this sharer has
share.message.content The Message content
share.message.network Network the share was distributed on.
share.campaign.id Unique identifier for the campaign associated with the share
share.campaign.name Name for the campaign associated with the share
share.campaign.published Whether the campaign for this share had been published. Expected to be true
share.campaign.referral_incentive.type The unit of the reward to be granted for a valid conversion
share.campaign.referral_incentive.value The amount of the reward_type to be given for a valid conversion
share.email_recipients A string representing of a JSON list of e-mail addresses this share was distributed to.
Only present if access to this field has been enabled for your account.
share.sharer.customer.id Friendbuy ID for the customer associated with the share
Only present when a customer id is passed via JavaScript
share.sharer.customer.detail_uri The Friendbuy REST API resource for the customer who originated this share.
share.sharer.customer.email Email for the customer associated with the share
Only present when a customer email is passed via JavaScript
share.sharer.customer.first_name The first name of the sharing customer, if given.
share.sharer.customer.last_name The last name of the sharing customer, if given.

Shares

After a successful share through Email, Facebook or Twitter, Friendbuy will send a POST request with a JSON body in the form of the following example to the provided URL. This only applies for shares via Email, Facebook and Twitter; it does not apply for shares via Personal URL (PURL).

Please note:
The Share Webhook should not be relied upon for implementing key logic in a referral program. It is fine to use Share Webhooks to retrieve valuable data, to store analytics, or to trigger various actions. However, a Personal URL (PURL) will not have a Share event associated with it - because it is only a copy & paste action - hence the Reward Webhook and Conversion Webhook from a PURL will not contain a Share ID and there will be never be a Share webhook fired for it.

Example POST Body

{
    "campaign": {
      "created_at": "2016-03-22 20:05:45.074247-07:00",
      "id": 333477,
      "name": "Widget Title",
      "published": true,
      "referral_incentive": {
        "type": "reward_amount",
        "value": 5.0
      }
    },
    "created_at": "2016-04-04 23:14:30.776253-07:00",
    "detail_uri": "https://api.friendbuy.com/v1/shares/132623",
    "id": 132623,
    "ip_address": "127.0.0.1",
    "referral_code": "aA",
    "message": {
      "content": "personal sharing message",
      "network": "email"
    },
    "email_recipients": ["friend@example.com"],
    "sharer": {
      "customer": {
        "account_id": "friendbuy-sharer",
        "detail_uri": "https://api.friendbuy.com/v1/customers/19486",
        "email": "sharer@example.com",
        "first_name": null,
        "id": 19486,
        "last_name": null
      },
      "email": "sharer@example.com",
      "facebook_friends_count": 0,
      "name": "",
      "twitter_followers_count": 0,
      "send_reminder": true,
      "newsletter_opt_in": true
    }
}
        

JSON Field Descriptions

Field Description
id Unique identifier for the share
referral_code String of characters used to attribute referral events to an advocate
created_at Date and time of share
detail_uri The Friendbuy REST API resource for this share.
email Email address of the person who shared
Only present if a valid email address was collected
facebook_friends_count How many facebook friends this sharer has
name The full name of the sharer, if given.
ip_address User IP address at the time of sharing
twitter_followers_count How many Twitter followers this sharer has
message.content The Message content
message.network Network the share was distributed on.
campaign.created_at Date and time of share
campaign.id Unique identifier for the campaign associated with the share
campaign.name Name for the campaign associated with the share
campaign.published Whether the campaign for this share had been published. Expected to be true
campaign.referral_incentive.type The unit of the reward to be granted for a valid conversion
campaign.referral_incentive.value The amount of the reward_type to be given for a valid conversion
email_recipients A string representing of a JSON list of e-mail addresses this share was distributed to.
Only present if access to this field has been enabled for your account.
sharer.customer.id Friendbuy ID for the customer associated with the share
Only present when a customer id is passed via JavaScript
sharer.customer.detail_uri The Friendbuy REST API resource for the customer who originated this share.
sharer.customer.email Email for the customer associated with the share
Only present when a customer email is passed via JavaScript
sharer.customer.first_name The first name of the sharing customer, if given.
sharer.customer.last_name The last name of the sharing customer, if given.
send_reminder True if the sharer would like a reminder sent if their friend has not made a purchase after 3 days.
newsletter_opt_in True if the sharer wants to be added to your newsletter mailing list.

Share Email Opt-outs

Merchants may choose to use their own share email opt-out list as a supplement to Friendbuy’s maintained email opt-out list. The Friendbuy maintained list consists of share recipients that have opted out from Friendbuy email shares or have been sent via the API endpoint Friendbuy provides for Merchants.

Overview of Integration Flow:

  1. Using your provided API endpoint, Friendbuy will request real-time authorization to share with recipients that an advocate enters into a Referral and Sharing widget in the form of email addresses.
  2. Your API will respond with a list of email addresses that have not opted out of receiving emails from your company.
  3. Friendbuy will send share emails to all recipients email addresses that are returned in the Merchant's response.
    1. Addresses sent in the request but not contained in the response will be excluded from the share.

Requirements:

  1. Merchant must implement an endpoint that will accept HTTPS POST requests.
    1. The POST body will be a JSON array of intended share recipient email addresses.
    2. The merchant will check each provided email address against its own system.
    3. A response with a status code of 200 is required within 30 seconds, and the response body must be JSON array of email addresses.
      1. A failure to respond will result in a retry
  2. To enable the feature, provide the URL for the above endpoint to your Friendbuy Customer Success Manager.

Example POST Body

[“Friend@example.com”, “Friend2@example.com”]

Example Merchant POST Responses


[“Friend2@example.com”]  // 1 approved address
[]  // no approved addresses
        

Custom Reward Validations

The custom reward validation webhook is an optional way for a Merchant to determine whether or not Friendbuy should fulfill the reward for a conversion based on proprietary 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).

Overview of Integration Flow:

  1. Each campaign that is intended to have custom reward validations must be configured as described under the requirements below.
  2. Using your provided API endpoint, and following any specified reward delay on the applicable campaign, Friendbuy will request validation for a pending reward.
  3. The request body will include details about the event that generated the conversion, such as the referrer, purchase date, order id, and more.
  4. A HTTP response code, returned by your system, between 200 and 299 will validate the reward, and instruct Friendbuy to issue the reward. Any other status will indicate the reward is invalid.

Requirements:

  1. Merchant must implement an endpoint that will accept HTTPS POST requests.
    1. A request's POST body will be the same content as Conversion API response
    2. A response with a status code is required within 30 seconds
      1. A status code in the range 200 and 299 will result in a validated reward.
      2. A response with a status of 403 will result in an invalid reward.
      3. A failure to respond will result in a retry
      4. A reward will be considered invalid if Friendbuy does not receive a response within 24 hours of its first validation attempt.
  2. Each campaign intended to use custom reward validations must be configured as follows:
    1. Create an endpoint as specified above
    2. Log in to Friendbuy.
    3. Navigate to the widget you want to add custom reward validations.
    4. Click "edit" to open the widget builder.
    5. Click "edit" under Reward > Criteria.
    6. Select "Validation URL" from the dropdown list, and click "Add."
    7. Enter the URL for the endpoint you have configured.
    8. Click "Save."


Retry Behavior

If the status code of a Webhook response is not 200, Friendbuy will retry the same POST request once per hour over the next 24 hours.

Verifying Requests are coming from Friendbuy

If you want to verify the authenticity of a webhook request from Friendbuy, you can verify the request’s cryptographic signature. When Friendbuy makes a call to your webhook, an authorization header is provided with the computed signature. You can follow the steps below to compute your own signature and compare it with ours.

Identifying the Authorization Header

For Custom Reward Validations, the authorization header is X-FRIENDBUY-SIGNATURE-V2. For all other webhooks: use X-FRIENDBUY-SIGNATURE.

Computing an Authorization Signature

  1. Using the JSON post body as a string, and your API secret key*, calculate an HMAC-SHA1 composition as follows: HMAC(api_secret, json_post)
  2. Base64 encode the resulting hash value.
  3. If the Base64 encoded hash matches authorization header then the request is valid.

* If webhooks are enabled for your account level, you can find your API Secret on the Webhooks tab in Friendbuy settings.

Here is example Python code that generates a webhook signature you can compare to the signature provided in the authorization header in order to verify the authenticity of the request:

from base64 import b64encode
from hashlib import sha1
import hmac
import urllib

# Create a signature:
#
# 1. The data to sign is assumed to be the json post body as a string
#
# 2. Sign the resulting string with HMAC-SHA1 using your API Secret as the key.
#
# 3. Base64 encode the resulting hash value.
#
# 4. If the signatures match, the response is valid.
#
def create_signature(api_secret, data):
    """
    Given the data for the request as a string, create an HMAC-SHA1 composition of
    that string and the API secret key.
    """
    mac = hmac.new(api_secret.encode("utf-8"), data.encode("utf-8"), sha1)
    computed = b64encode(mac.digest())
    return computed.strip()
        

Whitelisting Webhooks

To whitelist the Friendbuy webhooks, use the following IP addresses:

  • 50.18.110.159
  • 50.18.183.9