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