Skip to main content

Webhooks for Marketplace Affiliates

To get started, open Settings > Webhooks in the Refersion Marketplace. You can also open "Your Name" > Edit Your Profile and scroll to the Webhooks section. Both locations open 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.

To see webhooks in action before connecting your production service, add a temporary endpoint from a request-inspection service such as RequestCatcher.

Webhook Topics​

The following events can be sent to your URL endpoint from Refersion:

  • New Conversion
  • Conversion Approved
  • Conversion Denied
  • New Payment

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(s).

note

If you promote for multiple brands, you'll receive multiple webhooks per topic. For example, if you promote for 5 brands, you'll receive 5 "New Conversion" webhooks — one for each brand.

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: APPROVED_CONVERSION
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 you referred to a brand's store, and the commission earned as a result of your referral.

{
   "id":10308,
   "created":"2020-06-08 17:35:06",
   "status":"PENDING",
   "denied_reason_code":null,
   "is_recurring":false,
   "total_items":"2",
   "total":"59.00",
   "commission_total":"11.80",
   "currency":"USD",
   "is_test_conversion":"FALSE",
   "payment_status":"UNPAID",
   "updated":null,
   "affiliate":{
       "id":"12345678",
       "code":"9a4c"
   },
   "payment_id":null,
   "offer":{
       "id":null,
       "name":"Standard Affiliate Commission",
       "type":"PERCENT_OF_SALE",
       "amount":"20"
   },
   "coupon_code":"JAMES20",
   "order_id":null,
   "subscription_id":null,
   "reason":null,
   "notes":null,
   "product_names":[
      "PRODUCTA",
      "PRODUCTB"
   ],
   "click":{
   "created":"2020-06-08 17:35:06",
   "referer":null,
   "landed_url":null,
   "ip":null,
   "sub_id":null,
   "creative_id":null
   },
   "merchant":{
      "name":"Shoe Brand"
   }
}

Payments​

The New Payment webhook topic contains information about payments issued to you for the approved commission that you've earned. Every time a brand pays out commissions to you, a new webhook will be sent to a URL specified in the webhooks section.

{
   "id":2971,
   "payment_total":"500.00",
   "payment_method":"MANUAL",
   "conversions":[
      [
         {
            "id":"1234",
            "commission_total":"500.00",
            "currency":"USD"
         }
      ]
   ]
}
  • 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.