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:
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURERecommended 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-endpointsPOST /api/v1/webhook-endpointsGET /api/v1/webhook-endpoints/{id}PUT /api/v1/webhook-endpoints/{id}(orPATCH)DELETE /api/v1/webhook-endpoints/{id}POST /api/v1/webhook-endpoints/{id}/regenerate-secretPOST /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
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
nametarget_urleventsis_activemetadata
Available Events
transaction.successtransaction.failedtransaction.processingpayout.successpayout.failedpayout.processingpayout.cancelledkyc.submittedkyc.approvedkyc.rejectedcompany.suspendedcompany.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
{
"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 belowX-Webhook-IdX-Webhook-Event
Delivery and Retries
POSTmethod, JSON body,Content-Type: application/json.- Response timeout: 3 seconds. Any non-
2xxresponse, 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 inX-Webhook-Id). target_urlmust be anhttps://URL on a public domain name (500 characters max).- An endpoint created with an API key belongs to that key's environment (
SANDBOXorLIVE).
Signature Verification
The signature arrives in the Signature header: an HMAC-SHA256 of the raw request body, keyed with the endpoint secret.
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
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
2xxresponse - 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