> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clara.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Subscribers

> Manage webhook subscribers: create, update, add events, delete.

<Warning>This service is not yet available in v3. Available in **v1** only.</Warning>

# How to Use Subscribers Endpoints

This document focuses specifically on managing WebHook **Subscribers** using the Clara API endpoints under `/api/v1/subscribers`.

Each section includes request format, parameters, example payloads, and HTTP responses.

# How to Use Subscribers via Clara API

This document provides detailed usage instructions for the `/api/v1/subscribers` endpoint, including payloads, descriptions, and HTTP status codes.

***

## Create Subscriber

### Endpoint

```
POST /api/v1/subscribers
```

### Request Body

| Field       | Type      | Required | Description                                          |
| ----------- | --------- | -------- | ---------------------------------------------------- |
| name        | string    | ✅ Yes    | Name of the webhook subscriber                       |
| callbackUrl | string    | ✅ Yes    | URL to which webhook POSTs will be delivered         |
| events      | string\[] | ✅ Yes    | List of subscribed event types (e.g. `PAYMENT_PAID`) |
| enabled     | boolean   | ❌ No     | Whether the subscriber is active                     |
| companyUuid | uuid      | ❌ No     | Company UUID if not passed in credential             |

### Example

```json theme={null}
{
  "name": "My Webhook",
  "callbackUrl": "https://example.com/my/webhook/endpoint",
  "events": [
    "PAYMENT_PAID",
    "CARD_CREATION_REQUEST_CREATED"
  ],
  "enabled": true,
  "companyUuid": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
}
```

### Responses

| Status | Meaning                         |
| ------ | ------------------------------- |
| 201    | Subscriber created successfully |
| 400    | Bad Request                     |
| 401    | Unauthorized                    |
| 403    | Forbidden                       |

***

## Update Subscriber

### Endpoint

```
PATCH /api/v1/subscribers/{uuid}
```

### Request Body

| Field       | Type      | Required | Description                             |
| ----------- | --------- | -------- | --------------------------------------- |
| name        | string    | ❌ No     | Updated name                            |
| callbackUrl | string    | ❌ No     | New webhook target URL                  |
| events      | string\[] | ❌ No     | Updated list of event types             |
| enabled     | boolean   | ❌ No     | Whether the subscriber is active or not |
| companyUuid | uuid      | ❌ No     | Optional company identifier             |

### Example

```json theme={null}
{
  "name": "Updated Webhook",
  "callbackUrl": "https://api.company.com/hook",
  "events": [
    "CARD_CREATION_REQUEST_ERROR"
  ],
  "enabled": false
}
```

### Responses

| Status | Meaning            |
| ------ | ------------------ |
| 200    | Subscriber updated |
| 400    | Bad Request        |
| 401    | Unauthorized       |
| 403    | Forbidden          |

***

## Add Event to Subscriber

### Endpoint

```
POST /api/v1/subscribers/add-event
```

### Request Body

| Field       | Type   | Required | Description                                         |
| ----------- | ------ | -------- | --------------------------------------------------- |
| callbackUrl | string | ✅ Yes    | Callback URL of the target subscriber               |
| event       | string | ✅ Yes    | Event to add (e.g. `CARD_CREATION_REQUEST_CREATED`) |
| companyUuid | uuid   | ❌ No     | Optional company UUID                               |

### Example

```json theme={null}
{
  "callbackUrl": "https://example.com/my/webhook/endpoint",
  "event": "CARD_CREATION_REQUEST_CREATED"
}
```

### Responses

| Status | Meaning      |
| ------ | ------------ |
| 201    | Event added  |
| 400    | Bad Request  |
| 401    | Unauthorized |
| 403    | Forbidden    |

***

## Delete Event from Subscriber

### Endpoint

```
DELETE /api/v1/subscribers/delete-event
```

### Request Body

| Field       | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| callbackUrl | string | ✅ Yes    | Callback URL of the subscriber |
| event       | string | ✅ Yes    | Event to remove                |
| companyUuid | uuid   | ❌ No     | Optional company UUID          |

### Example

```json theme={null}
{
  "callbackUrl": "https://example.com/my/webhook/endpoint",
  "event": "CARD_CREATION_REQUEST_CREATED"
}
```

### Responses

| Status | Meaning       |
| ------ | ------------- |
| 204    | Event removed |
| 400    | Bad Request   |
| 401    | Unauthorized  |
| 403    | Forbidden     |

***

## Delete Subscriber

### Endpoint

```
DELETE /api/v1/subscribers/{uuid}
```

### Request Body

| Field       | Type | Required | Description           |
| ----------- | ---- | -------- | --------------------- |
| companyUuid | uuid | ❌ No     | Optional company UUID |

### Example

```json theme={null}
{
  "companyUuid": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
}
```

### Responses

| Status | Meaning            |
| ------ | ------------------ |
| 204    | Subscriber deleted |
| 400    | Bad Request        |
| 401    | Unauthorized       |
| 403    | Forbidden          |