Webhooks for affiliates

How to use webhooks

Webhooks can be configured to send data and notifications from your Attribution affiliates portal to other tools.

🚧

Webhook usage

Requests can be made for the following events:

  1. A conversion event has been completed
  2. A conversion has been approved and paid out

Create your webhook

You can create your webhook by navigating to the Profile page within your affiliates portal.

27482748

📘

Test your webhook

Use a tool like webhook.site to test and inspect webhooks.

  1. Add your webhook URL in the Profile > Webhooks section.
  2. Select a type when to send webhook and the request type POST/GET.
  3. Press Save and you will be able to test webhook.

TIP: Use a tool like webhook.site to see your payload

Please see request payload parameteres definitions below:

Parameter name

Description

conversion_id

Unique ID of conversion

landing_page_url

Landing page

landing_page_visited_at

Timestamp of user's visit in ISO8601 format

offer_name

Advertiser's offer name

offer_id

Advertiser's offer unique ID

project_name

Advertiser's name

project_id

Advertisers unique ID

atb_revenue

Revenue of conversion event

status

Status of conversion, can be one of:
captured - Conversion event detected
approved - Conversion accepted for payout to affiliate
rejected - Not accepted for payout to affiliate
payout_prepared - Conversion added to pending payout
completed - Payout is issued

affiliate_id

Your unique ID

payout

Amount to be paid to affiliate (if any)

params

Additional params you added to your affiliate URL. These can be subid or any parameters you like to track in webhook and reports.

POST webhook (sometimes called postback)

If your endpoint is expecting POST request we will send you JSON encoded body of all parameters listed above. Your additionally passed parameters will be passed as a hash under params property.

Please see the example request body below:

{
  "conversion_id": "c12345",
  "landing_page_url": "https://example.com/landing-page",
  "landing_page_visited_at": "2021-06-04T11:15:14.452Z",
  "offer_name": "Test offer",
  "offer_id": "o12345",
  "project_name": "Test project",
  "project_id": "p12345",
  "atb_revenue": 12.34,
  "payout": 1.23,
  "status": "captured",
  "affiliate_id": "a12345",
  "click_id": "c12345",
  "params": {
    "subid": "mysubid1",
    "custom_param": "param-value"
  }
}

GET webhook with auto parameters

If your endpoint expects GET webhook and you want to get all possible parameters, please select this option on the webhook settings form. Your custom parameters will be prefixed with params_, if you passed subid=1 to affiliate click URL it would returned as params_subid=1. All values of parameters would be URL-encoded.

After that you will be receiving GET requests with all the params now included in request URL parameters itself, e.g (line breaks are for readability only):

https://YOUR-ENDPOINT.COM?
affiliate_id=a12345&
atb_revenue=12.34&
click_id=c12345&
conversion_id=c12345&
landing_page_url=https%3A%2F%2Fexample.com%2Flanding-page&
landing_page_visited_at=2021-06-07T09%3A04%3A16.995Z&
offer_id=o12345&
offer_name=Test%20offer&
params_custom_param=param-value&
params_subid=mysubid1&
payout=1.23&
project_id=p12345&
project_name=Test%20project&
status=captured

GET webhook with custom parameters

If you want to send GET request with custom parameters you need to wrap every parameter value in {{ and }} for example if you enter webhook URL as https://YOUR-ENDPOINT.COM?UserClick={{click_id}}&State={{status}}&Revenue={{payout}}&MySubId={{subid}}, the request would look like (line breaks are for readability only):

https://YOUR-ENDPOINT.COM?
UserClick=c12345&
State=captured&
Revenue=1.23&
MySubId=subid

If you pass custom parameters to click URL like subid you can add these parameters also by simply wrapping them in {{ and }} e.g. if you added my_customer_parameter to click URL you can use it as {{my_customer_parameter}} in webhook URL.

If you have any questions please contact [email protected]