Webhooks

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.

curl -X POST https://api.caratuva.com/v1/webhooks \
  -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):

{
  "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/payments. 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/payments/:id/cancel` or by ops.
`payment_intent.expired`	`expiresAt` reached without payment.

Delivery format

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

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

Node.js example

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

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/webhooks/:id/deliveries to inspect failed deliveries and replay them manually if needed.

List subscriptions

curl https://api.caratuva.com/v1/webhooks \
  -H "X-API-Key: $CARATUVA_API_KEY"

Inspect deliveries

curl https://api.caratuva.com/v1/webhooks/<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

curl -X POST https://api.caratuva.com/v1/webhooks/<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)

curl -X DELETE https://api.caratuva.com/v1/webhooks/<id> \
  -H "X-API-Key: $CARATUVA_API_KEY"

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

Overview

Integration

Endpoints

Event types

Delivery format

Signature verification

Steps

Node.js example

Python example

Retries and backoff

List subscriptions

Inspect deliveries

Rotate the secret

Delete (deactivate)

​Subscribe

​Event types

​Delivery format

​Signature verification

​Steps

​Node.js example

​Python example

​Retries and backoff

​List subscriptions

​Inspect deliveries

​Rotate the secret

​Delete (deactivate)

Subscribe

Event types

Delivery format

Signature verification

Steps

Node.js example

Python example

Retries and backoff

List subscriptions

Inspect deliveries

Rotate the secret

Delete (deactivate)