Overview

KiraPay sends webhook notifications to your server when important events occur. This lets you react to events in real-time without polling our API.

How it works

1. Register your webhook endpoint URL with KiraPay

2. When an event occurs, KiraPay sends a POST request to your endpoint

3. Your server processes the webhook and returns a 200 status code

4. If we don't get a 200, we'll retry the delivery

   1. Additional retries with exponential backoff

   2. Maximum 3 retry attempts

Webhook events

Event	Description
transaction.created	A new transaction has been created
transaction.succeeded	A transaction completed successfully
transaction.failed	A transaction failed

Payload structure

{
  "id": "evt_1704067200000_abc123",
  "type": "transaction.succeeded",
  "createdAt": "2025-01-25T10:00:00.000Z",
  "data": {
    // Event-specific data
  }
}

Webhook headers

Header	Description
Content-Type	Always application/json
X-KiraPay-Event	Event type (e.g., transaction.succeeded)
X-KiraPay-Id	Unique event ID
X-KiraPay-Timestamp	Unix timestamp when event was created
X-KiraPay-Signature	HMAC-SHA256 signature for verification

Verifying webhooks

Always verify the signature to ensure requests are from KiraPay:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret, timestamp) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('base64');

  const expectedHeader = `sha256=${expectedSignature}`;
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedHeader)
  );
}

Managing endpoints

This is endpoints overview, you will learn more about it here.

Create endpoint

curl -X POST "https://api.kira-pay.com/api/admin/webhooks/endpoints" \
  -H "x-api-key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/kirapay",
    "secret": "whsec_your_webhook_secret"
  }'

List endpoints

curl -X GET "https://api.kira-pay.com/api/admin/webhooks/endpoints" \
  -H "x-api-key: YOUR_ADMIN_API_KEY"

Update endpoint

curl -X PATCH "https://api.kira-pay.com/api/admin/webhooks/endpoints/ENDPOINT_ID" \
  -H "x-api-key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-new-app.com/webhooks/kirapay"
  }'

View deliveries

curl -X GET "https://api.kira-pay.com/api/admin/webhooks/deliveries?endpointId=ENDPOINT_ID" \
  -H "x-api-key: YOUR_ADMIN_API_KEY"