Webhooks

Clara delivers webhook callbacks when card transaction events occur. You register a subscription — a callback URL, the transaction statuses you care about, and a signing secret — and Clara POSTs the event to your URL, signed with HMAC-SHA256.

Webhooks v1 (/api/v1/subscribers) is no longer available. See how to migrate to v3.

How it works

Create a subscription with POST /api/v3/webhooks/subscriptions.
When a matching transaction event occurs, Clara signs the exact JSON bytes and POSTs them to your callbackUrl.
Verify the X-Clara-Signature header before processing.
Deduplicate by event, then return 2xx quickly. Transient failures are retried (see Retries).

Events

Webhooks are scoped to one entity, CARD_TRANSACTIONS, with these statuses:

Status	Meaning
`NOTIFICATION`	A new card transaction was notified. It is usually the first event of a transaction.
`PRE_AUTHORIZED`	The transaction was pre-authorized.
`AUTHORIZED`	The transaction was authorized.
`SYSTEM_TRANSACTION`	A movement generated by Clara rather than by a card purchase.
`REJECTED`	The transaction was rejected.
`DELETED`	The transaction was deleted.
`REFUNDED`	A refund was finalized: `type` is `REFUND` and `status` is `AUTHORIZED`. Sent once per refund.

Subscribe only to the statuses you need: NOTIFICATION, PRE_AUTHORIZED and AUTHORIZED fire for every card purchase, and a single transaction usually goes through several of them, so they produce far more deliveries than the other statuses.

Payload

The body is the transaction event exactly as Clara’s transactions service publishes it: Clara does not wrap, filter or re-serialize it. Top-level fields:

Field	Description
`status`	The transaction’s operation type: `NOTIFICATION`, `PRE_AUTHORIZED`, `AUTHORIZED`, `SYSTEM_TRANSACTION`, `REJECTED` or `DELETED`.
`type`	The transaction type: `PURCHASE`, `REFUND`, `FEE`, `CREDIT` or `PAYMENT` (the same values as the Transactions API). It is not the webhook status.
`modelVersion`	Version of the event model.
`data`	The transaction: `uuid`, `companyUUID`, `authorizationNumber`, `card`, `claraMerchant`, `commercialName`, `operationInfo` (amounts, currencies, dates and `operationStatus`), `installment`, `invoice`, `invoiceTypeDescription`, `groups`, `labels`, `comment`, `locationName`, `user` (the cardholder), `billable`, `billingStartDate` and `billingEndDate`.

{
  "status": "REJECTED",
  "type": "PURCHASE",
  "modelVersion": 1,
  "data": {
    "uuid": "6f1d0c2e-9b3a-4c1d-8e2f-0a1b2c3d4e5f",
    "companyUUID": "2b0c9d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
    "authorizationNumber": "123456",
    "billable": true,
    "billingStartDate": null,
    "billingEndDate": null,
    "card": {
      "cardType": "CORPORATE PHYSICAL",
      "lastFourDigits": "1234",
      "cardUUID": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"
    },
    "claraMerchant": {
      "description": "Viajes",
      "descriptionEn": "Travel And Lodging",
      "descriptionPt": "Viagem E Hospedagem",
      "descriptionSp": "Viajes"
    },
    "commercialName": "Some Merchant",
    "groups": [],
    "installment": null,
    "invoice": { "type": "1021", "description": "CONSUMO NACIONAL" },
    "locationName": "HQ",
    "labels": [],
    "comment": "",
    "operationInfo": {
      "billingAmount": 150.75,
      "billingCurrency": "MXN",
      "originalAmount": 8.50,
      "originalCurrency": "USD",
      "approvedDate": "2026-08-27",
      "operationDate": "2026-08-27T14:35:00Z",
      "operationStatus": "REJECTED"
    },
    "user": {
      "email": "user@acme.com",
      "name": "Jane Doe",
      "role": "",
      "uuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
    }
  }
}

How each subscribed status appears in the body:

Subscribed status	How to recognize it
`NOTIFICATION`, `PRE_AUTHORIZED`, `AUTHORIZED`, `SYSTEM_TRANSACTION`, `REJECTED`, `DELETED`	`status` has the same value.
`REFUNDED`	`type` is `REFUND` and `status` is `AUTHORIZED` (the body keeps `AUTHORIZED`, not `REFUNDED`).

A refund is notified once, as REFUNDED, when it is finalized (status AUTHORIZED). Its earlier stages are not notified, and a subscription to AUTHORIZED alone does not receive refunds. A rejected or deleted refund is notified as REJECTED or DELETED.

Billing fields (for example billable and the billing dates) are filled after the event is emitted, so they are usually null in webhook payloads. Fetch the transaction from the Transactions API when you need them.

data.operationInfo.operationDate is the transaction’s creation time. There is no last-updated timestamp.
data.user is the cardholder.
data.labels and data.comment are not populated yet: expect them empty or absent.
data.invoice and data.invoiceTypeDescription are the bank concept of the movement; use type to tell purchases, refunds, fees, credits and payments apart.

DELETED events are emitted when a transaction is cleaned up and can carry fewer data fields than other events. data.uuid and data.companyUUID are always present.

Delivery

Each delivery is a POST to your callbackUrl with:

Header	Value
`Content-Type`	`application/json`
`X-Clara-Signature`	`t=<unix-timestamp>,v1=<hex hmac-sha256>`

The body is the raw JSON event. Do not re-serialize it before verifying the signature. Your endpoint must:

Be a public https URL. Private, loopback, link-local and cloud-metadata addresses are rejected when you create the subscription and again before every delivery.
Answer directly: redirects are not followed, and a 3xx counts as a failed delivery.
Accept the connection within 3 seconds and respond within 10 seconds. Acknowledge with 2xx first and process asynchronously.

Verifying the signature

The signature is HMAC-SHA256(secret, t + "." + rawBody), where secret is the subscription secret you provided, t is the t= value from the header, and rawBody is the exact request body.

const crypto = require("crypto");

function verify(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("="))
  );
  const expected = crypto
    .createHmac("sha256", secret)
    .update(parts.t + "." + rawBody)
    .digest("hex");
  const ok = crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1)
  );
  // Reject stale timestamps to prevent replays.
  return ok && Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
}

Verify against the raw request body exactly as received. Parsing and re-serializing the JSON changes the bytes and breaks the signature.

Before processing a delivery:

Verify the signature over the raw body.
Reject timestamps older than your tolerance (5 minutes is recommended) to block replays.
Deduplicate (see Delivery guarantees).

Delivery guarantees

Delivery is at-least-once. Clara does not deduplicate on your behalf: retries, resends and rare races can deliver the same event more than once. Store a key per processed event and ignore repeats. Use data.uuid together with the subscribed status (for example 6f1d0c2e-…:REJECTED): data.uuid identifies the transaction, which can produce more than one event.

Retries

Response	Result
`2xx`	Delivered.
`408`, `425`, `429`, any `5xx`, timeouts and connection or TLS errors	Retried with backoff.
Any other `4xx`, and `3xx`	Permanent failure: not retried.

Retries wait about 1 minute, 5 minutes, 15 minutes, 1 hour, 4 hours, 8 hours and 12 hours. A delivery is abandoned after 8 attempts or 48 hours, whichever comes first. Use resend to recover events after a long outage.

Circuit breaking

A circuit breaker per company and entity opens after repeated failures, so a failing endpoint does not receive a burst of requests. While it is open, deliveries are postponed and retried after the cooldown instead of being sent.

Sandbox

Test webhooks end to end without production data:

POST /api-test/v3/webhooks/subscriptions — register a sandbox subscription (environment = SANDBOX).
POST /api-test/v3/webhooks/events — submit a transaction event in the payload format. Clara delivers the exact bytes you submit, signed like a production delivery, synchronously to your enabled sandbox subscriptions, and returns the results.

See Sandbox for the full contract.

Resend stored events

Re-deliver stored events of your company within a date range to your current enabled subscriptions — not the subscription that originally received them, which may have been deleted. Useful to recover events after a callback outage. POST /api/v3/webhooks/{entity}/resend — scope write:subscribers. entity is CARD_TRANSACTIONS.

Parameter	In	Required	Description
`entity`	path	yes	`CARD_TRANSACTIONS`.
`dateFrom`	query	yes	Inclusive start date (`YYYY-MM-DD`).
`dateTo`	query	yes	Inclusive end date (`YYYY-MM-DD`). The range must not exceed 90 days.
`after`	query	no	Opaque cursor from a truncated response; pass it to fetch the next page.

curl -X POST "https://public-api.mx.clara.com/api/v3/webhooks/CARD_TRANSACTIONS/resend?dateFrom=2026-09-01&dateTo=2026-09-30" \
  -H "Authorization: Bearer $TOKEN"

202 Accepted — events are queued and delivered asynchronously (paced), so the counts describe queued work, not deliveries that already reached the subscriber:

{
  "entity": "CARD_TRANSACTIONS",
  "dateFrom": "2026-09-01",
  "dateTo": "2026-09-30",
  "eventsMatched": 12,
  "eventsResent": 12,
  "deliveriesQueued": 14,
  "eventsSkippedNoSubscriber": 0,
  "eventsSkippedUnavailable": 0,
  "truncated": false,
  "nextCursor": null
}

deliveriesQueued is the number of attempts submitted (one per current enabled subscription).
When the window holds more than 1000 events, only the oldest are queued and truncated is true; call again with after = nextCursor to continue.
Errors: 400 (missing dateFrom/dateTo, or a malformed cursor), 422 (unsupported entity, or a range wider than 90 days).

Delivery is at-least-once: deduplicate as described in Delivery guarantees. A resend shares the per-company/entity circuit breaker with live deliveries.

Next steps

Webhook Subscriptions — create, list, update, and delete subscriptions.

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

Webhooks

Webhooks

How it works

Events

Payload

Delivery

Verifying the signature

Delivery guarantees

Retries

Circuit breaking

Sandbox

Resend stored events

Next steps

​Webhooks

​How it works

​Events

​Payload

​Delivery

​Verifying the signature

​Delivery guarantees

​Retries

​Circuit breaking

​Sandbox

​Resend stored events

​Next steps

Webhooks

How it works

Events

Payload

Delivery

Verifying the signature

Delivery guarantees

Retries

Circuit breaking

Sandbox

Resend stored events

Next steps