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

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

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

{
  "id": 7654321,
  "affiliate_id": "123456",
  "trigger": "CUSTOMER@TRIGGER.COM",
  "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
  }
}