> ## 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.

# Notifications

> How Caratuva tells you what happened — in-product, by email and WhatsApp, and via webhooks.

Caratuva surfaces meaningful events through a few channels:

* **In-product** — a per-user inbox behind the bell in the dashboard, plus a Notifications delivery log.
* **Email** — automatic transactional emails for key lifecycle events.
* **WhatsApp** — settlement alerts to the seller's phone, when one is on file.
* **Outbound webhooks** — signed HTTP callbacks to your ERP for machine-to-machine reconciliation.

There are **no per-user notification preferences** today — transactional messages are event-driven, with recipients derived from the invoice/event rather than configured. For the webhook contract and signature verification, see the [Webhooks reference](/api-reference/webhooks).

## In-product notifications

The bell in the dashboard top bar opens a per-user **inbox** (powered by Courier) showing your unread alerts; read/unread state is per user, so two teammates on the same organization keep independent read state. There are no native filter-by-type or clear-all controls beyond what the inbox widget itself provides.

Separately, the **Notifications** page (`/notifications`) is a read-only **delivery log** of every message this organization has dispatched — with its channel, template, recipient, status, and reference — filterable by channel, status, and date range. It's the place to verify that a buyer invitation actually went out and answer "did the customer receive the link?"

## Email notifications

Caratuva automatically sends transactional emails for specific lifecycle events — for example buyer KYC approved/rejected, buyer invited, fiat received, on-chain confirmed, settled, and off-ramp failed. Recipients are derived from the invoice/event (the buyer or the seller, as appropriate); there are no per-event toggles, quiet hours, digest batching, or role-based opt-in settings.

Emails are sent from **`no-reply@caratuva.com`** — add it to your safe-sender list to avoid spam-filter delays.

<Note>
  There is no KYB/onboarding status-change email today — the seller's KYB status is shown live on the dashboard Payout page instead.
</Note>

## WhatsApp notifications

When a seller phone number is on file, Caratuva also sends the seller WhatsApp alerts for settlement-phase events (fiat received, on-chain confirmed, settled, off-ramp failed). This is automatic and not org-configurable. (SMS templates exist in the catalog but are not wired to any live flow — the buyer magic-link, for instance, is delivered by email.)

## Outbound webhooks

For machine reconciliation, register a URL that receives POST callbacks for the events you care about. Example use cases:

* Marking the order paid in your ERP when an invoice settles.
* Surfacing a payment-failed status to your sales team.
* Triggering downstream fulfillment when KYC clears.

### Subscribe

From the dashboard, **Developers → Webhooks**. Or via API — see [Webhooks reference](/api-reference/webhooks).

You provide:

* A URL (must be HTTPS).
* A list of event types.
* (Generated for you) A signing secret. Shown exactly once at creation — copy it into your secret manager immediately.

### Event types

Two parallel namespaces:

* `payment_intent.*` — fires for invoices created via the integrator API. Use these if you're an ERP/platform.
* `invoice.*` — fires for every invoice (both API-created and dashboard-created). Use these if your team operates the dashboard primarily.

The two namespaces are **not symmetric**: `invoice.*` exposes more granular states (e.g. `on_ramp_started`, `fiat_received`, `offramp_initiated`, `offramp_failed`) than `payment_intent.*`. Subscribe to one namespace or both, depending on how your team works.

The events you almost certainly want:

| Event                  | Why                                                      |
| ---------------------- | -------------------------------------------------------- |
| `*.created`            | An invoice came into existence.                          |
| `*.buyer_kyc_approved` | Buyer cleared KYC; payment is imminent.                  |
| `*.buyer_kyc_rejected` | Buyer failed KYC; this invoice won't be paid.            |
| `*.on_chain_confirmed` | Cross-border transfer confirmed on the settlement layer. |
| `*.settled`            | Funds in your bank account. **The big one.**             |
| `*.failed`             | Terminal failure. Surface or refund.                     |
| `*.cancelled`          | Cancelled by you, your team, or our ops.                 |
| `*.expired`            | Buyer didn't pay by the due date.                        |

The full event list and payload schemas are in the [Webhooks reference](/api-reference/webhooks).

### Delivery guarantees

* Caratuva attempts immediate delivery, then retries on any non-2xx response or transport error with exponential backoff: 30s, 2m, 10m, 1h, 6h, 24h. After seven attempts the delivery moves to `dead_letter` and we stop retrying.
* Each delivery carries a stable `X-Caratuva-Delivery-Id` — use it as an idempotency key on your side. Replays are inevitable; design for them.
* Each delivery carries an HMAC-SHA256 signature header. **Always verify it** against the raw request body before acting. Re-serializing the body breaks the signature.
* Endpoints must respond within 10 seconds.

### Inspecting deliveries

The dashboard shows recent deliveries per subscription, with status (`pending`, `delivered`, `dead_letter`), the upstream response code, and the next retry timestamp. Useful for diagnosing endpoint outages or signature mismatches. You can manually replay any delivery from the dashboard.

### Rotating the secret

If your webhook secret leaks, rotate it from **Developers → Webhooks → \[subscription] → Rotate secret**. The new secret is shown once.

Rotation is **immediate and atomic** — Caratuva stores one secret per subscription, so the old one stops verifying on the very next delivery; there is no dual-secret overlap window. Deploy the new secret to your verifier first (or atomically with the rotate call).

## Choosing a channel

| Use case                                             | Channel                                     |
| ---------------------------------------------------- | ------------------------------------------- |
| You want to confirm a buyer invitation actually sent | In-product (the Notifications delivery log) |
| Buyer/seller need a heads-up on a lifecycle event    | Email (sent automatically)                  |
| Seller wants a settlement ping on their phone        | WhatsApp (when a phone is on file)          |
| Finance needs to mark orders paid in the ERP         | Webhook                                     |
| Compliance needs an immutable trail                  | Webhook (and the audit log)                 |

A typical setup leans on automatic email/WhatsApp for awareness and webhooks for ERP-level reconciliation.