Overview

KiraPay Webhooks let your backend receive real‑time payment updates without polling. Once configured, KiraPay will send an HTTP POST request to your webhook URL whenever a transaction is created, succeeds, fails, or is refunded.

How it works

1. You register a webhook URL using POST /api/webhooks TRY HERE

2. KiraPay stores one webhook endpoint per API key

3. When an event happens, KiraPay sends a signed POST request to your URL

4. Your server verifies the signature and updates order state

Requirements

• A publicly reachable URL (not localhost unless tunneled)

• A secret (min 6 chars) for signature verification

• Your server must respond with 2xx to mark delivery successful

Webhook Headers

Every webhook includes:

• x-kirapay-signature - HMAC‑SHA256 of the raw payload using your webhook secret

• x-kirapay-timestamp - timestamp when webhook was sent

Signature Verification (Node.js example)

const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry Policy

If your server returns non‑2xx or times out, KiraPay retries:

• Max attempts: 5

• Intervals: 1 min, 5 min, 30 min, 2 hours, 24 hours

---

Webhook Payload

{
  "event": "transaction.succeeded",
  "timestamp": "2024-01-15T12:25:00.000Z",
  "data": {
    "transactionId": "64abc123def456789012349",
    "linkCode": "abc123xyz7",
    "customOrderId": "ORDER-123456",
    "amount": "100",
    "currency": "USDC",
    "sender": "0x123...",
    "receiver": "0x8356D265646a397b2Dacf0e05A4973E7676597f4",
    "status": "completed",
    "settlementAmount": "100"
  }
}