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.
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.
There is no KYB/onboarding status-change email today — the seller’s KYB status is shown live on the dashboard Payout page instead.
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.
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. |
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) |