API & Webhook

This guide helps you:

  1. Create and manage your API key

  2. Subscribe your store to UpPromote webhook events

  3. Jump to the developer docs for technical details when you’re ready

Get your API Key

For developing your own custom integration with UpPromote, you can create an API key. This is available from Professional plan.

To get the API key, simply go to Settings > Integration > Scroll down and find API Key > Get API Key

Then, please open our API documentation to read our available API endpoints

Using UpPromote Webhooks

Please read the webhook developer documentation for more details

Available webhook events

Webhook event
Description

referral.new

Occurs whenever there is a new referral in the store.

referral.approved

Occurs whenever a referral is approved.

referral.denied

Occurs whenever a referral is denied.

referral.status-changed

Occurs whenever status of a referral is changed.

affiliate.new

Occurs when there is a new affiliate in the store (signup or create manual).

affiliate.approved

Occurs whenever an affiliate is approved.

affiliate.inactive

Occurs whenever an affiliate is denied/deactivated.

affiliate.status-changed

Occurs whenever status of an affiliate is changed.

payment.paid

Occurs whenever an affiliate payment is marked as paid or processed.

Subscribe a webhook

You need to subscribe a webhook via API endpoint:

curl --location --request POST 'https://aff-api.uppromote.com/api/v2/webhook-subscriptions' \
--header 'Accept: application/json' \
--header 'Authorization: {{API_UPROMOTE_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "target_url": "https://example.com/webhooks/uppromote/referral-new",
    "event": "referral.new"
}'

Verifying webhook signatures

To ensure that webhook requests are coming from our servers and have not been tampered with, you need to verify the webhook signature included in the request headers.Each webhook request includes a header:

X-UpPromote-Signature: <signature>

The signature is generated using the HMAC-SHA256 algorithm with your subscription’s secret key and the raw request body. Your application should:

  • Retrieve the raw request body.

  • Get the X-Signature header value.

  • Compute an HMAC-SHA256 hash using the secret key and the raw body.

  • Compare the calculated hash with the received signature using a time-safe comparison.If they match, the webhook is valid. Otherwise, reject the request.

To learn more, please open this developer documentation for more details.

UpPromote developer documentation

When you’re ready for details (parameters, responses, and full webhook payloads), open the references:

Last updated