Webhooks are automated data packages sent from an app whenever specific events happen. In the affiliate world, webhooks are sometimes referred to as postbacks. While they share commonalities, they are not the same.

With postbacks, data is sent in the "Postback URL" via a query string with dynamic data inserted into URL parameters. With webhooks, the "Webhook URL" serves as a destination for sending data from one server to another server.

As a marketplace affiliate, you can leverage webhooks to receive notifications with information about conversions and payments for all the brands you promote for. Webhooks are triggered based on events that happen in your Marketplace account.

Setting up a webhook in your Marketplace account

To get started, click your name on the top right corner to reveal a dropdown, and then click Edit Your Profile.

Within your profile, scroll all the way to the bottom to find the webhooks section. Click "Create New Webhook"

A new window will pop up like the one below.

In the popup, you can choose a topic for receiving webhook notifications. Once a topic is selected, enter the URL where Refersion should send the webhook data. To see webhooks in action, you can set up a test URL to receive the webhooks. RequestCatcher is a great way to test for free.

Webhook Topics

Your webhook URL can receive any or all of the following topics/events from Refersion:

New Conversion
Conversion Approved
Conversion Denied
New Payment

You can configure multiple webhooks and specify which topics/events you wish to send to each URL. You can also select All Topics, in which case all the events listed above will send out to the designated URL(s).

Note: If you promote for multiple brands, you'll receive multiple webhooks per topic. For example, if you promote for 5 brands, you'll receive 5 "New Conversion" webhooks - one for each brand.

Webhook Data Overview and Examples:

The data you receive from the webhook will be in JSON format. Please see examples of our webhooks below:

Conversions

The New Conversion, Conversion Approved, and Conversion Denied webhook topics contain data about the order you referred to a brand's store, and the commission earned as a result of your referral.

Sample webhook data below:

{
   "id":10308,
   "created":"2020-06-08 17:35:06",
   "status":"PENDING",
   "denied_reason_code":null,
   "is_recurring":false,
   "total_items":"2",
   "total":"59.00",
   "commission_total":"11.80",
   "currency":"USD",
   "is_test_conversion":"FALSE",
   "payment_status":"UNPAID",
   "updated":null,
   "affiliate":{
       "id":"12345678",
       "code":"9a4c"
   },
   "payment_id":null,
   "offer":{
       "id":null,
       "name":"Standard Affiliate Commission",
       "type":"PERCENT_OF_SALE",
       "amount":"20"
   },
   "coupon_code":"JAMES20",
   "order_id":null,
   "subscription_id":null,
   "reason":null,
   "notes":null,
   "product_names":[
      "PRODUCTA",
      "PRODUCTB"
   ],
   "click":{
   "created":"2020-06-08 17:35:06",
   "referer":null,
   "landed_url":null,
   "ip":null,
   "sub_id":null,
   "creative_id":null
   },
   "merchant":{
      "name":"Shoe Brand"
   }
}

Payments

The New Payment webhook topic contains information about payments issued to you for the approved commission that you've earned. Every time a brand pays out commissions to you, a new webhook will be sent to a URL specified in the webhooks section.

Sample webhook data below:

{
   "id":2971,
   "payment_total":"500.00",
   "payment_method":"MANUAL",
   "conversions":[
      [
         {
            "id":"1234",
            "commission_total":"500.00",
            "currency":"USD"
         }
      ]
   ]
}