In Refersion, you can set up webhooks to receive notifications with information about affiliate activity, conversions and payments in your account.
To get started, navigate to Account > Settings > Webhooks. In 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.
Webhook Topics
The following events can be sent to your URL endpoint 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 Plans only)
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 endpoints.
Webhook Data Overview and Examples:
All webhooks are sent with HTTP headers a body in JSON format.
HTTP headers:
The HTTP headers give information about the webhook topic and a siguture 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: AFFILIATE_DETAILS_CHANGE
Webhook Payloads:
Conversions
The New Conversion, Conversion Approved, and Conversion Denied webhook topics, contain data about the order, the affiliate who referred the sale, the 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.
{
"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": "[email protected]"
},
"payment_id": null,
"offer": {
"id": 12345,
"name": "Standard Affiliate Commission",
"type": "PERCENT_OF_SALE",
"amount": "10"
},
"customer": {
"name": "Jane Doe",
"email": "[email protected]",
"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.
{
"data":{
"affiliates":{
"12345678":{
"id":"12345678",
"first_name":"John",
"last_name":"Smith",
"email":"[email protected]",
"paypal_email":"[email protected]",
"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":"[email protected]",
"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.
{
"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": "[email protected]",
"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.
{
"id": 7654321,
"affiliate_id": "123456",
"trigger": "[email protected]",
"type": "EMAIL"
}
Bonus Tier Movement
The Bonus Tier Movement webhook topic contains information about an affiliate and the new bonus tier milestone they achieved such as a new conversion milestone or a new sales benchmark reached. The information in this webhook topic may be useful for merchants looking to trigger rewards and/or reward emails outside of Refersion.
{
"id": "12345678",
"code": "b83713",
"status": "ACTIVE",
"last_login": "2023-04-11 17:19:48",
"last_conversion": "2023-04-11 20:32:12",
"first_name": "Jane",
"last_name": "Doe",
"email": "janedoe@examplecom",
"paypal_email": null,
"company": null,
"address_1": "123 Street Road",
"address_2": null,
"city": "Gotham",
"state": "NY",
"zip": "10018",
"country": "US",
"phone_number": null,
"source": "API",
"is_marketplace_user": false,
"custom_fields": [
{
"id": "32145",
"name": "Birthdate",
"value": "1989-01-01"
}
],
"offer": {
"id": "102237",
"name": "Standard Affiliate Commission"
},
"reward": {
"id": 250443,
"offer_id": "102237",
"milestone_reached": "1",
"amount_given": null,
"notes": null
}
}