# API & Webhook

{% hint style="success" %}
[New API version](https://aff-api.uppromote.com/docs/v2) available. Please open [our developer documentation](https://aff-api.uppromote.com/docs/v2) for more details!
{% endhint %}

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**](https://aff-api.uppromote.com/docs/v2) 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**

<figure><img src="/files/QmBUznmMWpmxChTS3O9t" alt=""><figcaption></figcaption></figure>

Then, please open our [API documentation](https://aff-api.uppromote.com/docs/v2) to read our available API endpoints

### Using UpPromote Webhooks

{% hint style="info" %}
Please read the [webhook developer documentation](https://aff-api.uppromote.com/docs/v2/webhook-overview-1623756m0) for more details
{% endhint %}

#### Available webhook events

<table><thead><tr><th width="289">Webhook event</th><th>Description</th></tr></thead><tbody><tr><td>referral.new</td><td>Occurs whenever there is a new referral in the store.</td></tr><tr><td>referral.approved</td><td>Occurs whenever a referral is approved.</td></tr><tr><td>referral.denied</td><td>Occurs whenever a referral is denied.</td></tr><tr><td>referral.status-changed</td><td>Occurs whenever status of a referral is changed.</td></tr><tr><td>affiliate.new</td><td>Occurs when there is a new affiliate in the store (signup or create manual).</td></tr><tr><td>affiliate.approved</td><td>Occurs whenever an affiliate is approved.</td></tr><tr><td>affiliate.inactive</td><td>Occurs whenever an affiliate is denied/deactivated.</td></tr><tr><td>affiliate.status-changed</td><td>Occurs whenever status of an affiliate is changed.</td></tr><tr><td>payment.paid</td><td>Occurs whenever an affiliate payment is marked as paid or processed.</td></tr></tbody></table>

#### Subscribe a webhook

You need to subscribe a webhook via [**API endpoint**](https://aff-api.uppromote.com/docs/v2/subscribe-a-webhook-event-21170080e0):&#x20;

```
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](https://aff-api.uppromote.com/docs/v2/webhook-overview-1623756m0#verifying-webhook-signatures) for more details.&#x20;

### UpPromote developer documentation

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

* API Reference: <https://aff-api.uppromote.com/docs/v2/api-overview-1615961m0>
* Webhook Reference: <https://aff-api.uppromote.com/docs/v2/webhook-overview-1623756m0>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.uppromote.com/settings/integrations/api-and-webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.