Webhooks are automated data packages that are sent from an application whenever a specific event or events happen. You can think of webhooks like a notification, just like the ones you receive on your phone.
In Refersion you can set up webhooks to receive notifications about affiliate activity as well as conversions in your account.
Setting up a webhook in Refersion
To get started, navigate to Account > Settings > Webhooks (on the bottom left) and then click + Create New Webhook.
A new window will pop up like the one below.
From the popup, choose the appropriate topic (see list below) from which you’d like to trigger a webhook notification. Once a topic is selected you’ll enter the webhook URL where Refersion should send the webhook data.
Note: 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 the following topics/events from Refersion:
New Conversion
Conversion Approved
Conversion Denied
New Payment
New Affiliate
Affiliate Status Change
Affiliate Details Change
New Conversion Trigger
Bonus Tier Movement (Enterprise plan required)
You can configure multiple webhooks and specify which topics/events you wish to send to each webhook URL. You can also select All Topics, in which case all the events listed above will trigger a notification to the designated URL(s).
Webhook Data Overview and Examples:
The data you receive from the webhook will be in JSON format. Please see a few examples below:
Conversions
The New Conversion, Conversion Approved, and Conversion Denied webhook topics contain data about the order, the referring affiliate, that affiliate's offer details, and the click data associated with the order. The information in this webhook topic may be useful for merchants looking to route conversion data into a third-party system or send branded conversion notification emails to affiliates from an ESP like Klaviyo or Mailchimp.
Sample webhook data below:
{
"id": 987654321,
"created": "2020-02-14 18:48:42",
"status": "PENDING",
"denied_reason_code": null,
"is_recurring": false,
"total_items": "1",
"total": "130.55",
"commission_total": "10.00",
"currency": "USD",
"is_test_conversion": "FALSE",
"payment_status": "UNPAID",
"updated": null,
"affiliate": {
"id": "123456",
"code": "123ab",
"first_name": "John",
"last_name": "Smith",
"email": "JohnSmith@email.com"
},
"payment_id": null,
"offer": {
"id": 12345,
"name": "Standard Affiliate Commission",
"type": "PERCENT_OF_SALE",
"amount": "10"
},
"customer": {
"name": "Jane Doe",
"email": "JaneDoe@email.com",
"browser_ip": "11.222.333.44"
},
"coupon_code": null,
"order_id": "1022",
"subscription_id": null,
"reason": null,
"notes": null,
"product names": null,
"click": {
"created": "2019-11-06 18:44:41",
"referer": null,
"landed_url": "https://samplestore.com/?rfsn=3321631.89b4ba",
"ip": "00.111.222.33",
"sub_id": null,
"creative_id": null
},
"source": "SHOPIFY"
}
Payments
The New Payment webhook topic contains information about payments made to affiliates. The information in this webhook topic may be useful for merchants looking to route payment records to an external book-keeping system or for other payment-related automation.
Sample webhook data below:
{
"data":{
"affiliates":{
"12345678":{
"id":"12345678",
"first_name":"John",
"last_name":"Smith",
"email":"johnsmith@email.com",
"paypal_email":"johnsmith@email.com",
"payments":[
{
"id":"191558",
"created":1599666692,
"total_conversions":"13",
"payment_method":"MANUAL",
"commission_total":"230.03",
"total":"763.30",
"currency":"USD",
"note":null
}
]
},
"1802931":{
"id":"1802931",
"first_name":"Jane",
"last_name":"Doe",
"email":"jane@email.com",
"paypal_email":null,
"payments":[
{
"id":"191558",
"created":1599666692,
"total_conversions":"2",
"payment_method":"MANUAL",
"commission_total":"39.10",
"total":"391.00",
"currency":"USD",
"note":null
}
]
}
}
}
}
Affiliates
The New Affiliate, Affiliate Status Change, and Affiliate Details Change webhook topics contain data about the affiliate's name, address, registration details, custom fields, and offer. The information in this webhook topic may be useful for merchants looking to route affiliate data into a CRM, email marketing/newsletter system, or e-commerce system.
Sample webhook data below:
{
"id": 123456,
"code": "123ab",
"status": "PENDING",
"last_login": "0000-00-00 00:00:00",
"last_conversion": "0000-00-00 00:00:00",
"first_name": "John",
"last_name": "Smith",
"email": "johnsmith@email.com",
"paypal_email": null,
"company": "",
"address_1": "123 Street Road",
"address_2": "Suite 7",
"city": "New York",
"state": "NY",
"zip": "11111",
"country": "",
"phone_number": "",
"source": "MERCHANT_PROFILE",
"custom_fields": [
{
"id": "55555",
"name": "INSTAGRAM HANDLE",
"value": "Bee_Handle"
}
],
"offer": {
"id": "44444",
"name": "Tiered Offer"
},
"is_marketplace_user": false
}
Conversion Triggers
The New Conversion Trigger webhook topic contains information related to newly added conversion triggers in your account. The information in this webhook topic may be useful for merchants looking to auto-create coupons/discount codes in their e-commerce platforms after they are created in Refersion.
Sample webhook data below:
{
"id": 7654321,
"affiliate_id": "123456",
"trigger": "CUSTOMER@TRIGGER.COM",
"type": "EMAIL"
}
Bonus Tier Movement (Enterprise plan required)
To compliment our bonus tiers feature, we’ve also created webhook notifications to notify merchants when affiliates reach a new milestone. In the webhook data, you’ll see the current milestone of the affiliate in either the number of conversions or in sales amounts. In addition, the affiliate’s address and custom field information is provided so merchants can potentially utilize the data to send rewards outside of Refersion.
Sample webhook data below:
{
"id": "12345678",
"code": "0979",
"status": "ACTIVE",
"last_login": "0000-00-00 00:00:00",
"last_conversion": "2019-12-06 15:42:04",
"first_name": "Joe",
"last_name": "Smith",
"email": "joeshmo@gmail.com",
"paypal_email": "joeshmo@gmail.com",
"company": "Refersion",
"address_1": "123 Street Road",
"address_2": "Suite 123",
"city": "New York",
"state": "NY",
"zip": "10010",
"country": "US",
"phone_number": "2122225555",
"source": "API",
"is_marketplace_user": false,
"custom_fields": null,
"offer": {
"id": "123",
"name": "Standard Affiliate Commission"
},
"reward": {
"id": 88,
"offer_id": "123",
"milestone_reached": "1",
"amount_given": null,
"notes": “"
}
}