Webhooks & Security

Security is at the heart of Tsara’s infrastructure.
This section explains how to securely handle webhooks, authenticate requests, and protect your integration from unauthorized access or tampering.

🧩 Webhook Overview

Tsara uses webhooks to notify your application about important events — such as payments, transfers, or verifications.
These events are signed using your Webhook Secret Key, ensuring that only Tsara can trigger them.

Typical webhook event types:

payment.success
fiat.received
offramp.success
customer.verified

🔐 Signature Validation

Every webhook request contains a signature header that you must verify before processing:

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

This signature is computed using:

hash_hmac('sha512', $payload, TSARA_SECRET_KEY)

Where:

$payload → The exact raw request body received.
TSARA_SECRET_KEY → Your webhook secret from the Tsara Dashboard.

🧾 Example Verification (PHP)

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

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

// Parse the event
$event = json_decode($payload, true);

if ($event['type'] === 'payment.success') {
    // Handle payment event
}

http_response_code(200);
?>

⚙️ Example Verification (Node.js)

import crypto from "crypto";
import express from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/tsara", (req, res) => {
  const payload = req.body.toString();
  const signature = req.headers["x-tsara-signature"];
  const expected = crypto
    .createHmac("sha512", process.env.TSARA_SECRET_KEY)
    .update(payload)
    .digest("hex");

  if (signature !== expected) {
    return res.status(400).send("Invalid signature");
  }

  const event = JSON.parse(payload);
  console.log("Received event:", event.type);
  res.sendStatus(200);
});

🛡️ Webhook Security Checklist

✅ Always verify X-Tsara-Signature before processing.
✅ Accept only HTTPS connections for webhooks.
✅ Store your Webhook Secret Key securely (not in frontend code).
✅ Use retry-safe logic — webhooks are idempotent.
✅ Respond with 200 OK immediately after successful processing.
✅ Log every received event with its event.id for audit purposes.

🧱 API Key Security

Use Environment Variables
Store all API keys (TSARA_SECRET_KEY, TSARA_PUBLIC_KEY, etc.) in environment variables, not in code repositories.
Restrict Access
Only grant access to developers or systems that require it.
Rotate Keys Regularly
You can rotate or revoke keys anytime in Dashboard → Developers → API Keys.
Use Separate Keys per Environment
Keep distinct keys for sandbox and production to avoid cross-environment mix-ups.

🧠 Common Pitfalls

❌ Failing to verify webhook signatures → Anyone could spoof fake events.
❌ Logging your secret key in server logs → Exposes credentials.
❌ Returning 4xx or 5xx errors without retry handling → You’ll miss events.
❌ Using the same key for test and live → Leads to environment conflicts.

🧩 Recommended Webhook Endpoint Setup

Environment	Example Endpoint	Purpose
Sandbox	`https://sandbox.yourapp.com/webhooks/tsara`	Testing and development.
Production	`https://api.yourapp.com/webhooks/tsara`	Live webhook receiver.

💡 Configure endpoints separately for each environment under your Tsara Dashboard → Developers → Webhooks.

🔗 Related Pages

Webhooks — Payment, Stablecoin, Fiat, and Customer webhook events.
Errors — Handle webhook delivery or validation errors.
SDKs & Libraries — Code examples for signature verification.
Authentication — Learn how to authorize API requests securely.