> For the complete documentation index, see [llms.txt](https://docs.sparkloop.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkloop.app/api-v3/endpoints/webhooks.md).

# Webhooks

## Webhooks

A **Webhook** delivers an HTTP `POST` to a URL you control whenever one of the subscribed events happens on your account. Webhooks are account-scoped and fully manageable through the API — list, retrieve, create, update, and delete.

Subscribable events: `new_referral`, `reward_unlocked`, `reward_redeemed`, `sync_subscriber`, `new_partner_referral`, `new_partner_pending_referral`, `new_opportunity`. (`new_offer_lead` is read-only — it's tied to an offer and managed in the dashboard.)

### List webhooks

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/webhooks`

Paginated.

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "webhooks": [
    <Webhook Object>
  ],
  "meta": {
    "per_page": 50,
    "page": 1,
    "total_pages": 1,
    "total_webhooks": 3
  }
}
```

{% endtab %}
{% endtabs %}

### Get webhook

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/webhooks/:uuid`

**Path Parameters**

| Name                                   | Type   | Description         |
| -------------------------------------- | ------ | ------------------- |
| uuid<mark style="color:red;">\*</mark> | String | The webhook's UUID. |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "webhook": <Webhook Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}
{% endtabs %}

### Create webhook

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v3/webhooks`

**Request Body**

| Name                                  | Type   | Description                           |
| ------------------------------------- | ------ | ------------------------------------- |
| url<mark style="color:red;">\*</mark> | String | The destination URL. Must be `https`. |
| events                                | Array  | The event names to enable.            |

```json
{
  "webhook": {
    "url": "https://example.com/hooks/sparkloop",
    "events": ["new_referral", "reward_unlocked"]
  }
}
```

{% tabs %}
{% tab title="201: Created" %}

```json
{
  "webhook": <Webhook Object>
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```json
{
  "error": "Unsupported event(s): foo"
}
```

{% endtab %}
{% endtabs %}

### Update webhook

<mark style="color:orange;">`PUT`</mark> `https://api.sparkloop.app/v3/webhooks/:uuid`

Supplying `events` replaces the whole set; omit it to change `url` alone.

**Path Parameters**

| Name                                   | Type   | Description         |
| -------------------------------------- | ------ | ------------------- |
| uuid<mark style="color:red;">\*</mark> | String | The webhook's UUID. |

**Request Body**

| Name   | Type   | Description                           |
| ------ | ------ | ------------------------------------- |
| url    | String | The destination URL. Must be `https`. |
| events | Array  | Replacement set of event names.       |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "webhook": <Webhook Object>
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```json
{
  "error": "Unsupported event(s): foo"
}
```

{% endtab %}
{% endtabs %}

### Delete webhook

<mark style="color:red;">`DELETE`</mark> `https://api.sparkloop.app/v3/webhooks/:uuid`

**Path Parameters**

| Name                                   | Type   | Description         |
| -------------------------------------- | ------ | ------------------- |
| uuid<mark style="color:red;">\*</mark> | String | The webhook's UUID. |

{% tabs %}
{% tab title="204: No Content" %}

```
(empty response)
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```json
{
  "error": "A sponsor on a custom ESP must keep a partner-referral webhook."
}
```

{% endtab %}
{% endtabs %}