🔌 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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "companyUuid": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
}

Responses

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