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

You may configure your Friendbuy account to use webhooks with these steps:

  • Log in to Friendbuy
  • Go to Settings
  • Go to the Webhooks tab
  • Enter the URL for the 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.

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.

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": {
      "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": {
        "date": "2016-04-13 16:21:26.424652",
        "email": "friend@example.com",
        "ip_address": "127.0.0.1",
        "new_customer": "yes",
        "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.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.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.share.id 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.content 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": {
      "date": "2016-04-04 23:21:04.145113",
      "email": "friend@example.com",
      "ip_address": "127.0.0.1",
      "new_customer": "yes",
      "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
        },
        "email": "sharer@example.com",
        "facebook_friends_count": 0,
        "name": "",
        "twitter_followers_count": 0
      }
    },
    "status": "unmarked"
}
        

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
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
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.
share.id 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.content 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
    }
}
        

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

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, a X-FRIENDBUY-SIGNATURE header is provided with the computed signature. You can follow the steps below to compute your own signature and compare it with ours.

  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 X-FRIENDBUY_SIGNATURE 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 X-FRIENDBUY_SIGNATURE 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