Skip to main content

Webhooks for Merchants

In Refersion, you can set up webhooks to receive notifications with information about affiliate activity, conversions and payments in your account.

To get started, open Settings > Webhooks in Refersion. The Webhooks page opens the embedded webhook management portal, where you can:

  • Add, edit, or remove endpoint URLs.
  • Choose the events sent to each endpoint.
  • Inspect delivery attempts and replay failed deliveries.
  • Rotate an endpoint's signing secret.

If your plan does not include webhook access, the page displays an upgrade prompt instead of the management portal.

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 as an HTTP POST with a JSON body. See Receiving Webhooks for the response your endpoint must return and how to verify a delivery signature.

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
  }
}