Webhooks

Configure webhook endpoints, verify signatures, and design reliable asynchronous event processing.

Introduction

Webhooks allow Genuka Pay to notify your backend about transaction, payout, KYC, and company events without forcing your system to poll continuously.

Event Delivery

Receive asynchronous updates when transactions, payouts, or compliance states change.

Signature Verification

Validate every incoming delivery before applying state changes in your backend.

Secret Rotation

Regenerate webhook secrets when credentials change or exposure is suspected.

Required Headers

Webhook endpoint management calls should include:

Authenticated Webhook Management Request

X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

Recommended Setup Flow

Start with the Webhooks page if you want to manage endpoints from the dashboard.

You can use that page to:

create endpoints

choose subscribed events

enable or disable delivery

inspect endpoint metadata

rotate the webhook secret

Use the API when you want to automate setup or provision endpoints from your own tooling.

Endpoint Management API

GET /api/v1/webhook-endpoints

POST /api/v1/webhook-endpoints

GET /api/v1/webhook-endpoints/{id}

PUT /api/v1/webhook-endpoints/{id}

DELETE /api/v1/webhook-endpoints/{id}

POST /api/v1/webhook-endpoints/{id}/regenerate-secret

Create a Webhook Endpoint

Create Webhook Endpoint

curl -X POST "{{BASE_URL}}/api/v1/webhook-endpoints" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production backend",
    "target_url": "https://merchant.example.com/webhooks/genuka",
    "events": [
      "transaction.success",
      "transaction.failed",
      "payout.success",
      "kyc.approved"
    ],
    "is_active": true
  }'

Main Request Fields

name

target_url

events

is_active

metadata

Available Events

transaction.success

transaction.failed

transaction.processing

transaction.refunded

payout.success

payout.failed

payout.processing

payout.cancelled

kyc.submitted

kyc.approved

kyc.rejected

company.created

company.suspended

company.reactivated

Delivery Payload Shape

Example Webhook Payload

{
  "id": "01HW...",
  "event": "transaction.success",
  "timestamp": "2026-04-01T12:10:00Z",
  "data": {
    "transaction_id": "01HR...",
    "track_id": "TRX_01HR...",
    "status": "SUCCESS"
  }
}

Relevant delivery headers may include:

X-Webhook-Id

X-Webhook-Event

Signature Verification

Webhook delivery uses HMAC-SHA256 with the webhook secret.

verify-webhook.ts

import crypto from "crypto";

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

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

Secret Rotation

Rotate Webhook Secret

curl -X POST "{{BASE_URL}}/api/v1/webhook-endpoints/{id}/regenerate-secret" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE"

Store the regenerated secret immediately. It may not be displayed again later.

Recommendations

acknowledge webhook deliveries quickly with a 2xx response

push heavy work to a queue or worker

verify the signature before mutating business state

make your receiver idempotent

correlate webhook IDs with internal reconciliation records

Event Delivery

Signature Verification

Secret Rotation

On this page