Developers

Webhooks 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


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.

Types

There are two types of webhooks, Conversion and Sharing. For more information and the properties for each type, see below.

Conversion

After a successful conversion Friendbuy will POST the following properties to the provided URL.

Field Description
conversion_id Unique identifier for the conversion
new_order_id Id for new order
new_order_ip_address User IP address at the time of new order
new_order_date Date the new order was generated
new_order_customer_id Customer id for new order
Only present if customer id was provided for the new order
new_order_customer_email Customer email for new order
Only present if customer email was provided for the new order
possible_self_referral True or False indicating that the shopper may have self referred.
reward_type Type of reward/incentive offered either cash, points or revenue share (%)
Only present for incentivized campaigns
reward_amount The amount to reward for the campaign.
Only present for incentivized campaigns
shopper_revenue_share Deprecated. Percentage of revenue share offered for the campaign
Only present for campaigns with revenue share reward
shopper_fixed_revenue Deprecated, use reward_amount instead. Dollar amount of incentive offered for the campaign
Only present for campaigns with fixed revenue reward
shopper_fixed_points Deprecated. Points amount offered for the campaign
Only present for campaigns with fixed points reward
email Email address of referrer
Only present if a valid email address was collected
network The network the referral was posted to
Either facebook, twitter or email or personal_url
share_id Unique identifier for the share
Only present for conversions generated from shares
share_ip_address User IP address at the time of sharing
Only present for conversions generated from shares
share_campaign_id Unique identifier for the campaign associated with the share
Only present for conversions generated from shares
share_campaign_name Name for the campaign associated with the share
Only present for conversions generated from shares
share_customer_id Id for the customer associated with the share
Only present for conversions generated from shares when a customer id is passed via JavaScript
share_customer_email Email for the customer associated with the share
Only present for conversions generated from shares when a customer email is passed via JavaScript
share_parameters Custom parameters and additional parameters, if any, that were supplied with the sharing widget
Always present but empty if no parameters were supplied
original_order_id Id for the original order associated with the share
Only present for post-purchase share
original_order_customer_id
Id for the customer associated with the original order
Only present for post-purchase share when a customer id is passed via JavaScript
original_order_customer_email Email for the customer associated with the original order
Only present for post-purchase shares when a customer email is passed via JavaScript
personal_url_customer_id Id for the customer associated with the personal url
Only present for conversions generated from personal urls
personal_url_customer_email Email for the customer associated with the personal url
Only present for conversions generated from personal urls
personal_url_campaign_id Unique identifier for the campaign associated with the personal url
Only present for conversions generated from personal urls
personal_url_campaign_name Name for the campaign associated with the personal url
Only present for conversions generated from personal urls
personal_url_parameters Custom parameters and additional parameters, if any, that were supplied with the original sharing widget
Always present but empty if no parameters were supplied
new_customer Whether or not the new order was made by a new customer, as passed into the conversion tracker.

Sharing

After a successful share Friendbuy will POST the following properties to the provided URL.

Field Description
share_id Unique identifier for the share
ip_address User IP address at the time of sharing
message Message content
campaign_id Unique identifier for the campaign associated with the share
campaign_name Name for the campaign associated with the share
facebook_message_id Facebook message identifier
Only present for shares into Facebook
twitter_message_id Twitter message identifier
Only present for shares into Twitter
linkedin_message_id LinkedIn message identifier
Only present for shares into LinkedIn
created_at Date and time of share
order_id Order id for the share
Only present for post-purchase share
customer_id ID for the customer associated with the share
Only present when a customer id is passed via JavaScript
customer_email Email for the customer associated with the share
Only present when a customer email is passed via JavaScript
email Email address of the person who shared
Only present if a valid email address was collected
parameters Custom parameters and additional parameters, if any, that were supplied with the widget
Always present but empty if no parameters were supplied
reward_type Type of reward/incentive offered either cash, points or revenue share (%)
Only present for incentivized campaigns
reward_amount The amount to reward for the campaign.
Only present for incentivized campaigns

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 header or querystring parameter is provided with the computed signature. You can follow the steps below to compute your own signature and compare it with ours.

  1. Take the full URL of the webhook URL including the querystring.
  2. If the request is a POST, sort all of the POST parameters alphabetically (using Unix-style case-sensitive sorting order).
  3. Iterate through the sorted list of POST parameters, and append the variable name and value (with no delimiters) to the end of the URL string.
  4. Sign the resulting string with HMAC-SHA1 using your API Secret as the key.
  5. Base64 encode the resulting hash value.
  6. Compare your hash to the one in the X-Friendbuy-Signature header. If the signatures match, 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 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:

Whitelisting Webhooks

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

  • 50.18.110.159
  • 50.18.183.9