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 with HTTP headers and a body in JSON format.

HTTP headers

The HTTP headers identify the webhook topic and contain the Svix values used to validate the delivery. See Webhook Validation for verification instructions and the legacy compatibility header.

Content-Length: 813
Content-Type: application/json
Refersion-Topic: AFFILIATE_DETAILS_CHANGE
svix-id: msg_2abc123
svix-timestamp: 1775606400
svix-signature: v1,example-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
  }
}

Related

• Webhook Validation — verify that an incoming webhook really came from Refersion.
• Introduction — how webhooks work and when to use them.
• API Reference — how to authenticate, and every endpoint the Refersion API exposes.