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

# Webhooks

> Subscribe to payment-intent lifecycle events. HMAC-signed, retried with exponential backoff.

Outbound webhooks are how Caratuva tells your ERP about every state change on a payment intent — buyer KYC approved, transfer confirmed, settled, failed. You register a URL and an event list once, then verify the HMAC signature on each delivery.

## Subscribe

```bash theme={null}
curl -X POST https://api.caratuva.com/v1/webhook-subscriptions \
  -H "X-API-Key: $CARATUVA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://erp.example.com/webhooks/caratuva",
    "eventTypes": [
      "payment_intent.created",
      "payment_intent.buyer_kyc_approved",
      "payment_intent.on_chain_confirmed",
      "payment_intent.settled",
      "payment_intent.failed",
      "payment_intent.cancelled",
      "payment_intent.expired"
    ]
  }'
```

Response (the `secret` field is the only place the signing secret ever appears):

```json theme={null}
{
  "id": "cksub_123...",
  "orgId": "ckorg_456...",
  "url": "https://erp.example.com/webhooks/caratuva",
  "eventTypes": ["payment_intent.created", "payment_intent.settled", "..."],
  "active": true,
  "createdAt": "2026-05-02T14:00:00.000Z",
  "updatedAt": "2026-05-02T14:00:00.000Z",
  "secret": "whsec_<base64>"
}
```

Store `secret` immediately — Caratuva encrypts it at rest and cannot return it again. If you lose it, rotate it.

## Event types

Two parallel namespaces:

* `payment_intent.*` — fires only for invoices created via `POST /v1/payment-intents`. Subscribe to these if you're a B2B integrator. You will not see noise from any dashboard activity.
* `invoice.*` — fires for every invoice (both API-created and dashboard-created). Subscribe to these only if you also operate the dashboard.

The full list of `payment_intent.*` events:

| Event                               | When                                                                           |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| `payment_intent.created`            | Intent created via API; buyer not yet engaged.                                 |
| `payment_intent.buyer_kyc_approved` | Buyer's KYC submission cleared identity verification.                          |
| `payment_intent.buyer_kyc_rejected` | KYC rejected. Intent terminates at `failed`.                                   |
| `payment_intent.on_chain_confirmed` | Cross-border transfer confirmed on Caratuva's settlement layer.                |
| `payment_intent.settled`            | PIX payout completed; funds in the seller's BRL account. Terminal happy state. |
| `payment_intent.failed`             | Terminal failure (any phase). `data` carries the reason.                       |
| `payment_intent.cancelled`          | Cancelled via `POST /v1/payment-intents/:id/cancel` or by ops.                 |
| `payment_intent.expired`            | `expiresAt` reached without payment.                                           |

## Delivery format

```http theme={null}
POST /webhooks/caratuva HTTP/1.1
Host: erp.example.com
Content-Type: application/json
X-Caratuva-Signature: t=1714658400,v1=8c9f...sha256hex
X-Caratuva-Delivery-Id: ckdel_789...
X-Caratuva-Event-Type: payment_intent.settled

{
  "event": "payment_intent.settled",
  "data": {
    "paymentIntentId": "ckabc123...",
    "externalId": "INV-2026-00042",
    "amount": "12500.00",
    "currency": "USD",
    "metadata": { "orderId": "42" }
  }
}
```

Endpoints must respond with a 2xx status within 10 seconds. Anything else is treated as a delivery failure.

## Signature verification

The signature header is `t=<unix_ts>,v1=<sha256_hex>`. The signed payload is `${t}.${rawBody}` (the raw HTTP body bytes, not a re-serialized JSON object). Always verify against the raw bytes — re-serializing changes whitespace and key order and breaks the MAC.

### Steps

1. Parse `t` and `v1` from the `X-Caratuva-Signature` header.
2. Reject the request if `|now - t| > 300` (5-minute replay window).
3. Compute `expected = HMAC-SHA256(secret, "${t}.${rawBody}")` and compare hex-encoded against `v1` with a constant-time comparator.
4. Use `X-Caratuva-Delivery-Id` as an idempotency key on your side — replays with the same id should be no-ops.

### Node.js example

```ts theme={null}
import { createHmac, timingSafeEqual } from 'node:crypto';
import express, { Request, Response } from 'express';

const SECRET = process.env.CARATUVA_WEBHOOK_SECRET!;
const REPLAY_WINDOW_SECONDS = 300;

const app = express();

// Capture raw body — express.json() throws away the bytes we need to verify.
app.post(
  '/webhooks/caratuva',
  express.raw({ type: 'application/json' }),
  (req: Request, res: Response) => {
    const header = req.header('x-caratuva-signature');
    if (!header) return res.status(401).json({ error: 'missing signature' });

    const parts = Object.fromEntries(
      header.split(',').map((p) => p.trim().split('=', 2)),
    ) as { t?: string; v1?: string };
    if (!parts.t || !parts.v1) return res.status(401).json({ error: 'malformed signature' });

    const t = Number(parts.t);
    if (!Number.isFinite(t)) return res.status(401).json({ error: 'malformed signature' });

    const now = Math.floor(Date.now() / 1000);
    if (Math.abs(now - t) > REPLAY_WINDOW_SECONDS) {
      return res.status(401).json({ error: 'timestamp out of window' });
    }

    const rawBody = (req.body as Buffer).toString('utf8');
    const expected = createHmac('sha256', SECRET)
      .update(`${t}.${rawBody}`)
      .digest('hex');

    const a = Buffer.from(expected, 'hex');
    const b = Buffer.from(parts.v1, 'hex');
    if (a.length !== b.length || !timingSafeEqual(a, b)) {
      return res.status(401).json({ error: 'bad signature' });
    }

    const event = JSON.parse(rawBody) as { event: string; data: unknown };
    // Idempotency: dedupe on x-caratuva-delivery-id before mutating state.
    handleEvent(req.header('x-caratuva-delivery-id')!, event);

    res.status(204).end();
  },
);
```

### Python example

```python theme={null}
import hmac, hashlib, time
from flask import Flask, request, abort

SECRET = os.environ["CARATUVA_WEBHOOK_SECRET"].encode()
REPLAY_WINDOW = 300

app = Flask(__name__)

@app.post("/webhooks/caratuva")
def handle():
    header = request.headers.get("X-Caratuva-Signature", "")
    parts = dict(p.strip().split("=", 1) for p in header.split(","))
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1:
        abort(401)
    if abs(int(time.time()) - int(t)) > REPLAY_WINDOW:
        abort(401)

    raw = request.get_data()
    expected = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, v1):
        abort(401)

    event = request.get_json(force=True)
    delivery_id = request.headers["X-Caratuva-Delivery-Id"]
    handle_event(delivery_id, event)
    return "", 204
```

## Retries and backoff

Caratuva attempts immediate delivery, then retries on any non-2xx or transport error with exponential backoff:

| Attempt | Delay since previous |
| ------- | -------------------- |
| 1       | (immediate)          |
| 2       | 30s                  |
| 3       | 2m                   |
| 4       | 10m                  |
| 5       | 1h                   |
| 6       | 6h                   |
| 7       | 24h                  |

After the seventh attempt the delivery flips to `dead_letter` and Caratuva stops retrying. Use `GET /v1/webhook-subscriptions/:id/deliveries` to inspect failed deliveries and replay them manually if needed.

## List subscriptions

```bash theme={null}
curl https://api.caratuva.com/v1/webhook-subscriptions \
  -H "X-API-Key: $CARATUVA_API_KEY"
```

## Inspect deliveries

```bash theme={null}
curl https://api.caratuva.com/v1/webhook-subscriptions/<id>/deliveries?limit=50 \
  -H "X-API-Key: $CARATUVA_API_KEY"
```

Each row carries `attempt`, `status` (`pending` | `delivered` | `failed` | `dead_letter`), the upstream `responseStatus`, and the next `nextAttemptAt`. In practice the values you'll see today are `pending`, `delivered`, and `dead_letter` — a row stays `pending` between retries and flips to `dead_letter` after the final attempt; `failed` is reserved.

## Rotate the secret

```bash theme={null}
curl -X POST https://api.caratuva.com/v1/webhook-subscriptions/<id>/rotate-secret \
  -H "X-API-Key: $CARATUVA_API_KEY"
```

The response carries the new `secret` exactly once. Rotation is **immediate and atomic** — the API stores only one secret per subscription, so the old secret stops verifying on the very next delivery and there is no dual-secret overlap window. Deploy the new secret to your verifier first (or atomically with the rotate call); any in-flight or retried deliveries are re-signed with the new secret when they're sent. Don't configure your verifier to accept "either" secret expecting an overlap — there isn't one.

## Delete (deactivate)

```bash theme={null}
curl -X DELETE https://api.caratuva.com/v1/webhook-subscriptions/<id> \
  -H "X-API-Key: $CARATUVA_API_KEY"
```

Soft-deletes the subscription (`active=false`). No further deliveries fire; historical `deliveries` rows remain queryable.