Webhook Integration Guide

Katu9 supports webhooks to notify your application of important events, such as when a transaction is created. This guide explains how to receive, verify, and process webhooks securely.

Receiving Webhooks

Register your webhook endpoint URL in the Katu9 dashboard or via the API.
Choose the events you want to subscribe to (e.g., transaction.created).
Katu9 will send a POST request to your endpoint for each event.

Webhook Request Structure

Method: POST
Headers:
- Content-Type: application/json
- X-Katu9-Signature: HMAC SHA256 signature of the payload (see below)
- X-Webhook-Event: Event name (e.g., transaction.created)
Body:
{ "event": "transaction.created", "data": { ...transaction fields... } }

Verifying the Signature

To ensure the webhook is from Katu9 and hasn't been tampered with:

Retrieve your webhook's secret from the dashboard or API.
Compute the HMAC SHA256 hash of the raw request body using your secret.
Compare the computed hash (as a hex string) with the value in the X-Katu9-Signature header.
- If they match, the webhook is authentic.

Example (Node.js)

const crypto = require("crypto");
 
function verifySignature(secret, payload, signature) {
  const hmac = crypto.createHmac("sha256", secret);
  hmac.update(payload, "utf8");
  const digest = hmac.digest("hex");
  return digest === signature;
}
 
// Usage in an Express route
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-katu9-signature"];
  const secret = process.env.KATU9_WEBHOOK_SECRET;
  const isValid = verifySignature(secret, req.body, signature);
  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }
  // Parse and process the event
  const event = JSON.parse(req.body);
  // ... handle event.event and event.data
  res.status(200).send("OK");
});

Best Practices

Always verify the signature before processing the event.
Respond with a 2xx status code quickly; Katu9 will retry on failure.
Log received events for debugging/audit.
Use HTTPS for your webhook endpoint.

Supported Events

transaction.created: Triggered when a new transaction is created.
payment_link.created: Triggered when a new payment link is generated for a transaction (including regenerated links).

The payload for payment_link.created is:

{
  "event": "payment_link.created",
  "data": {
    "id": "pl_xxxxxxxxxxxx",
    "merchantId": "merchant_xxx",
    "amount": 1000,
    "currency": "INR",
    "redirectUrl": "https://...",
    "expiresAt": "2023-05-12T11:00:00.000Z",
    "environment": "PRODUCTION",
    "description": "Regenerated payment link",
    "status": "ACTIVE",
    "createdAt": "2023-05-12T10:00:00.000Z",
    "updatedAt": "2023-05-12T10:00:00.000Z",
    "transactionId": "tx_xxxxxxxxxxxx"
  }
}

More events will be added in the future. Subscribe only to the events you need.

For more details or troubleshooting, contact support@katu9.com.

Webhooks