To get started, navigate to "Your Name" > 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

The following events can be sent to your URL endpoint 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:

All webhooks are sent with HTTP headers and a body in JSON format.

HTTP headers:

The HTTP headers give information about the webhook topic and a signature from Refersion. The Refersion-Signature header can be used to validate webhooks coming from Refersion. See "Webhook Validation" for more information.

Content-Length: 813
Content-Type: application/json
Refersion-Signature: abcdefghijklmnopqrstuvwxzy12345678==
Refersion-Topic: APPROVED_CONVERSION

Webhook Payloads:

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.

{
   "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.

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