Webhook Subscriptions

A subscription tells Clara where to send webhook events, which transaction statuses you want, and the secret used to sign deliveries. It replaces the deprecated v1 /api/v1/subscribers (events) model. Base path: /api/v3/webhooks/subscriptions (production) · /api-test/v3/webhooks/subscriptions (sandbox).

Authentication

Use an OAuth 2.0 Bearer token with:

Scope	Grants
`read:subscribers`	List and get subscriptions.
`write:subscribers`	Create, update, and delete subscriptions.

The subscription object

Field	Type	Description
`uuid`	uuid	Subscription identifier (server-generated).
`entity`	string	Event entity. Currently `CARD_TRANSACTIONS`.
`statuses`	string[]	Transaction statuses to receive: `NOTIFICATION`, `PRE_AUTHORIZED`, `AUTHORIZED`, `SYSTEM_TRANSACTION`, `REJECTED`, `DELETED`, `REFUNDED`. See Events.
`callbackUrl`	string	Public HTTPS URL that receives the `POST`.
`enabled`	boolean	Whether deliveries are active. Defaults to `true`.
`environment`	string	`PRODUCTION` or `SANDBOX`.
`createdAt`	timestamp	Creation time (ISO 8601).
`updatedAt`	timestamp	Last update time (ISO 8601).

The signing secret is write-only: it is required on create, may be replaced on update, and is never returned in any response. Clara stores it encrypted.

A company can hold one subscription per entity, per environment. Each subscription needs its own callbackUrl: a production and a sandbox subscription cannot share the same URL, so give the sandbox one a different path or query string (for example https://client.example.com/webhooks?env=sandbox).

The signing secret

You choose the secret; Clara never generates it. Generate 32 random bytes and encode them as unpadded base64url (43 characters, alphabet A-Z a-z 0-9 - _, no =). For example:

openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

Secrets that are not canonical unpadded base64url, or that do not meet the length requirement, are rejected with 400.
Use a different secret per environment (sandbox and production).
There is no endpoint verification step: a subscription is active as soon as it is created. A wrong secret or callback URL shows up as failed deliveries, so test the setup in sandbox first.
To rotate, send the new value with PUT. It takes effect immediately, with no grace period, so make your endpoint accept signatures from both the old and the new secret before the PUT, and drop the old one afterwards.

Create a subscription

POST /api/v3/webhooks/subscriptions — scope write:subscribers.

{
  "callbackUrl": "https://client.example.com/webhooks",
  "entity": "CARD_TRANSACTIONS",
  "statuses": ["REJECTED", "REFUNDED"],
  "secret": "voIkfFK4kbVW34AqmOtdrOodqNdwWooc507WRf2OROY"
}

201 Created:

{
  "uuid": "7f4c2a1b-2d3e-4f50-8a91-123456789abc",
  "entity": "CARD_TRANSACTIONS",
  "statuses": ["REJECTED", "REFUNDED"],
  "callbackUrl": "https://client.example.com/webhooks",
  "enabled": true,
  "environment": "PRODUCTION",
  "createdAt": "2026-09-10T12:00:00Z",
  "updatedAt": "2026-09-10T12:00:00Z"
}

Status	Meaning
`400`	Missing or invalid `secret` (see The signing secret), or an invalid body.
`409`	The company already has a subscription for this entity in this environment, or another of its subscriptions already uses this `callbackUrl`.
`422`	Validation error, for example an unsupported status, or a `callbackUrl` that is not public `https`.

List subscriptions

GET /api/v3/webhooks/subscriptions — scope read:subscribers. Returns the authenticated company’s subscriptions. Secrets are never returned.

Get a subscription

GET /api/v3/webhooks/subscriptions/{uuid} — scope read:subscribers. Returns 404 if the subscription does not belong to the authenticated company.

Update a subscription

PUT /api/v3/webhooks/subscriptions/{uuid} — scope write:subscribers. Partial update of callbackUrl, statuses, enabled, and/or secret.

{
  "statuses": ["REFUNDED"],
  "enabled": true,
  "secret": "ovk0lTk0fb8HucqKC9Cdtut5LCxx9Xe9tRsSNYpeC38"
}

A new secret takes effect immediately. Setting enabled: false stops deliveries without deleting the subscription.

While a subscription is disabled, matching events are not stored or queued: they are not delivered when you re-enable it and cannot be resent. Disable a subscription only when you can afford to miss those events.

Delete a subscription

DELETE /api/v3/webhooks/subscriptions/{uuid} — scope write:subscribers. Returns 204 No Content; audit history is retained.

Next steps

Webhooks — event delivery, signature verification, retries, and the sandbox.

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

Webhook Subscriptions

Webhook Subscriptions

Authentication

The subscription object

The signing secret

Create a subscription

List subscriptions

Get a subscription

Update a subscription

Delete a subscription

Next steps

​Webhook Subscriptions

​Authentication

​The subscription object

​The signing secret

​Create a subscription

​List subscriptions

​Get a subscription

​Update a subscription

​Delete a subscription

​Next steps

Webhook Subscriptions

Authentication

The subscription object

The signing secret

Create a subscription

List subscriptions

Get a subscription

Update a subscription

Delete a subscription

Next steps