Webhooks

Stablecoin webhooks allow Tsara to notify your application in real-time when important stablecoin events occur on the Solana network — such as deposits, transfers, or ramp conversions.

This ensures your system stays in sync with on-chain activity and can automate actions like crediting user balances or updating dashboards.

Overview

Event Type	Description
stablecoin.received	USDC received into a wallet or address.
stablecoin.sent	Outgoing transfer successfully completed.
onramp.success	Fiat → USDC conversion completed.
offramp.success	USDC → Fiat conversion completed.
onramp.failed	Fiat → USDC conversion failed.
offramp.failed	USDC → Fiat conversion failed.

Example Payloads

stablecoin.received

{
  "id": "evt_101",
  "type": "stablecoin.received",
  "created_at": "2025-10-17T12:00:00Z",
  "data": {
    "wallet_id": "wal_123",
    "address": "4bH...xyz",
    "amount": "75.00",
    "asset": "USDC",
    "network": "solana",
    "onchain_tx": "5qu...abc"
  }
}

stablecoin.sent

{
  "id": "evt_102",
  "type": "stablecoin.sent",
  "created_at": "2025-10-17T12:10:00Z",
  "data": {
    "wallet_id": "wal_123",
    "to_address": "8vR...def",
    "amount": "10.00",
    "asset": "USDC",
    "network": "solana",
    "onchain_tx": "7as...xyz"
  }
}

onramp.success

{
  "id": "evt_103",
  "type": "onramp.success",
  "created_at": "2025-10-17T12:20:00Z",
  "data": {
    "onramp_id": "onr_456",
    "wallet_id": "wal_123",
    "fiat_currency": "NGN",
    "stablecoin": "USDC",
    "amount_stablecoin": "98.50",
    "rate": "1 USDC = 1015 NGN"
  }
}

offramp.success

{
  "id": "evt_104",
  "type": "offramp.success",
  "created_at": "2025-10-17T12:30:00Z",
  "data": {
    "offramp_id": "offr_789",
    "wallet_id": "wal_123",
    "stablecoin": "USDC",
    "amount_stablecoin": "200.00",
    "fiat_currency": "NGN",
    "amount_fiat": 203000,
    "status": "completed"
  }
}

Signature Verification

All webhook requests from Tsara include a header:

X-Tsara-Signature: <HMAC-SHA512 hash>

You must verify this signature using your Webhook Secret Key from the dashboard to ensure authenticity.

Example (PHP)

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_TSARA_SIGNATURE'] ?? '';
$expected = hash_hmac('sha512', $payload, TSARA_WEBHOOK_SECRET);

if (!hash_equals($expected, $signature)) {
    http_response_code(400);
    exit('Invalid signature');
}

$event = json_decode($payload, true);
if ($event['type'] === 'stablecoin.received') {
    // Handle incoming USDC
}

http_response_code(200);
?>

Retry Behavior

Tsara retries failed webhook deliveries using exponential backoff (1s → 5s → 30s).
If your endpoint doesn’t return a 2xx status, Tsara will attempt delivery up to 5 times.
Webhooks are idempotent — you may receive the same event more than once. Always check the event.id before processing.

Best Practices

Always verify the signature using your Webhook Secret Key.
Log all incoming webhook payloads for debugging and auditing.
Ensure your webhook endpoint responds quickly (within 5s).
Use event.id or onchain_tx to prevent double processing.
Acknowledge successfully processed events with HTTP 200 OK.

Wallet — Create and manage stablecoin wallets.
Ramping — Onramp and Offramp between fiat and USDC.
Payment Links — Collect USDC directly from customers.
Integrations — Learn supported networks, tes