Logo GenukaGenuka Pay
API Reference

Webhooks

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

Introduction

Webhooks let Genuka Pay notify your backend of payment state changes (and Subscriptions module events) through signed HTTP requests, 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

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} (or PATCH)
  • DELETE /api/v1/webhook-endpoints/{id}
  • POST /api/v1/webhook-endpoints/{id}/regenerate-secret
  • POST /api/v1/webhook-endpoints/{id}/test

The signing secret is returned on creation, when you retrieve an endpoint, and when you regenerate it, never in the list. POST /{id}/test sends a signed webhook.test event shaped exactly like a real delivery, so you can test your signature verification.

Create a Webhook Endpoint

Create Webhook Endpoint
curl -X POST "https://api-pay.genuka.com/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",
      "transaction.processing"
    ],
    "is_active": true
  }'

Main Request Fields

  • name
  • target_url
  • events
  • is_active
  • metadata

Available Events

  • transaction.success
  • transaction.failed
  • transaction.processing
  • payout.success
  • payout.failed
  • payout.processing
  • payout.cancelled
  • kyc.submitted
  • kyc.approved
  • kyc.rejected
  • company.suspended
  • company.reactivated

Events actually emitted

Today only transaction.success, transaction.failed and transaction.processing (plus the subscription events) are sent. payout.*, kyc.*, company.suspended and company.reactivated are accepted when subscribing an endpoint but are not emitted yet: do not build logic that waits for them. Track payouts with GET /api/v1/payouts/{id}.

transaction.refunded and company.created can no longer be chosen: Genuka Pay has no refunds, and a company exists before its endpoints. An endpoint already subscribed keeps them, without ever receiving them.

transaction.* events cover payins: API payments, hosted checkout and collection links.

Subscription events (customer.*, subscription.*, invoice.*) are listed in Subscription webhooks.

Delivery Payload Shape

Example Webhook Payload
{
  "id": "01HW...",
  "event": "transaction.success",
  "timestamp": "2026-09-19T12:10:00.000000Z",
  "data": {
    "transaction_id": "01HR...",
    "idempotency_key": "...",
    "amount": 10000,
    "net_amount": 9575,
    "provider_fee_amount": 150,
    "genuka_fee_amount": 275,
    "total_fee_amount": 425,
    "currency": "XOF",
    "status": "SUCCESS",
    "completed_at": "2026-09-19T12:10:00.000000Z",
    "metadata": { "external_id": "order_10001" }
  }
}

Your own reference comes back in data.metadata.external_id, the one you sent at initiation. For a payment made through a hosted checkout, data.metadata is the session's metadata.

data.transaction_id is the payment id. The transaction.success and transaction.failed events do not carry a track_id: match them on transaction_id, idempotency_key or metadata.external_id.

transaction.failed

{
  "id": "01HW...",
  "event": "transaction.failed",
  "timestamp": "2026-09-19T12:10:00.000000Z",
  "data": {
    "transaction_id": "01HR...",
    "idempotency_key": "order_10001",
    "status": "FAILED",
    "reason": "Insufficient balance",
    "failure": { "code": "INSUFFICIENT_FUNDS", "message": "Insufficient balance" },
    "details": { "...": "..." },
    "failed_at": "2026-09-19T12:10:00.000000Z",
    "metadata": { "external_id": "order_10001" }
  }
}

failure.code is one of: INSUFFICIENT_FUNDS, INCORRECT_PIN, INVALID_PAYER, LIMIT_EXCEEDED, ACCOUNT_RESTRICTED, PAYMENT_DECLINED, PAYMENT_EXPIRED, PROVIDER_ERROR, UNKNOWN. failure.message is written to be shown to your customer.

transaction.processing

{
  "id": "01HW...",
  "event": "transaction.processing",
  "timestamp": "2026-09-19T12:09:30.000000Z",
  "data": {
    "transaction_id": "01HR...",
    "status": "PROCESSING",
    "provider_reference": "...",
    "track_id": "JK-01k7c4t9m2y8x5b3n6q0r1s2t4",
    "processing_at": "2026-09-19T12:09:30.000000Z"
  }
}

Sent when the request reaches the operator, unless the final outcome is already known.

Delivery headers:

  • Signature — HMAC-SHA256 of the request, see below
  • X-Webhook-Id
  • X-Webhook-Event

Delivery and Retries

  • POST method, JSON body, Content-Type: application/json.
  • Response timeout: 3 seconds. Any non-2xx response, or no response, triggers a retry.
  • 3 attempts in total, with exponential backoff. After that the delivery is dropped: plan a polling-based reconciliation.
  • Arrival order is not guaranteed, and the same delivery can arrive twice: deduplicate on id (also in X-Webhook-Id).
  • target_url must be an https:// URL on a public domain name (500 characters max).
  • An endpoint created with an API key belongs to that key's environment (SANDBOX or LIVE).

Signature Verification

The signature arrives in the Signature header: an HMAC-SHA256 of the raw request body, keyed with the endpoint secret.

verify-webhook.ts
import crypto from "crypto";

// rawBody: the request body exactly as received, before any JSON parsing.
export function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const received = Buffer.from(signature, "utf8");
  const computed = Buffer.from(expected, "utf8");

  return (
    received.length === computed.length &&
    crypto.timingSafeEqual(received, computed)
  );
}

Sign the raw body, not the reparsed object

Re-serialising the JSON after parsing it changes whitespace and key order: the signature will no longer match. Keep the raw body (express.raw(), an unparsed request.body) for verification. Compare in constant time, and reject any unsigned delivery.

Secret Rotation

Rotate Webhook Secret
curl -X POST "https://api-pay.genuka.com/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

How is this guide?

Last updated on