Skip to main content

Webhooks

A webhook is an HTTPS POST we send to your server when something happens, such as a payment completing or a payout failing. Use webhooks as your source of truth for payment outcomes, and keep GET /v1/transactions/{id} as a fallback.

Where things are

Set up webhooks in the portal under Integrations → Webhooks. The same page holds your signing secret and the delivery log. For what each event contains, see Webhook events.

How it works​

Set up an endpoint​

In the portal, open Integrations → Webhooks and add an endpoint:

SettingNotes
Endpoint URLMust be HTTPS and answer 2xx directly. Redirects are not followed, so register the final URL, trailing slash included.
EventsThe events this endpoint receives. Leave empty to receive every notification event.
DescriptionOptional, to tell endpoints apart.
ActiveSwitch off to pause deliveries without deleting the endpoint.

You can register up to 10 endpoints, for example one for deposits and one for payouts, or separate endpoints for accounting and fulfilment. Every matching endpoint receives each event, with the same event id.

One secret for all endpoints

All your endpoints are signed with a single secret, shown on the same page. It starts with whsec_. If it leaks, rotate it. The old secret stops working immediately, and the next delivery is signed with the new one, so update your server first or be ready to handle a brief window of failures.

What a delivery looks like​

Every delivery is a POST with a JSON body:

{
"id": "0b0e9a3c-8f1d-4a7b-b1a2-3c4d5e6f7a8b",
"eventType": "transaction.completed",
"timestamp": "2026-07-18T09:15:00.000Z",
"data": {
"id": "a3f1c2d4-5e6b-7a8c-9d0e-1f2a3b4c5d6e",
"type": "STK_PUSH",
"status": "COMPLETED",
"amount": 1500,
"currency": "KES",
"accountReference": "INV-1001",
"externalId": "your-transaction-id",
"receiptNumber": "SGL1234ABC"
},
"metadata": {
"event": "deposit.transaction.completed"
}
}

The data object is abridged here. Every field is listed in Webhook events.

FieldMeaning
idUnique per event. Shared by every endpoint that receives it, and reused on a resend.
eventTypeThe delivery type: transaction.completed, transaction.failed, transaction.settled or webhook.test.
metadata.eventThe specific, subscribable name, for example deposit.transaction.completed.
dataThe transaction. data.id is the transactionId you were given at creation.

Headers on every delivery:

HeaderValue
Content-Typeapplication/json
X-Webhook-EventThe eventType, e.g. transaction.completed
X-Webhook-Signaturesha512=<hex HMAC of the raw body>

Deliveries time out after 30 seconds. Respond with a 2xx as soon as you have verified and stored the event.

Verify the signature​

The signature is an HMAC-SHA512 of the raw request body, keyed with your webhook secret, hex-encoded and prefixed with sha512=. Always verify it before trusting a delivery. Compute it over the raw body, not a re-serialized object, because re-serializing can change whitespace and key order.

const crypto = require('crypto');
const express = require('express');

const app = express();

app.post(
'/webhooks/transactions',
express.raw({ type: 'application/json' }), // keep the raw body
(req, res) => {
const received = (req.get('X-Webhook-Signature') || '').replace(/^sha512=/, '');
const expected = crypto
.createHmac('sha512', process.env.WEBHOOK_SECRET)
.update(req.body)
.digest('hex');

const ok =
received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(received, 'hex'));

if (!ok) return res.status(401).send('invalid signature');

const event = JSON.parse(req.body);
// handle event.eventType / event.metadata.event / event.data ...
res.sendStatus(200);
},
);

If you use the Node SDK, constructWebhookEvent() and verifyWebhookSignature() do this for you.

Handle deliveries safely​

  • Acknowledge fast. Return 200 immediately and process asynchronously. A slow handler risks the 30-second timeout.
  • Be idempotent. Deliveries are at-least-once, and a resend reuses the original event id. De-duplicate on id, and make each state change safe to apply twice.
  • Do not rely on order. If you are unsure of the current state, fetch GET /v1/transactions/{id}. The API is the source of truth.
  • Key on data.status, not just eventType. A card payment sends transaction.completed twice, once when approved and once when settled. See card payments.
  • Do not fulfil from the browser. A client-side callback or returnUrl is a UX signal, not proof of payment.

Failed deliveries​

A delivery counts as failed if your endpoint returns a non-2xx status, times out, or redirects. A failure never undoes the payment. It is recorded and skipped, so keep a poll or reconciliation job as a backstop.

Every attempt, success or failure, is kept in the delivery log on the same portal page. For each event you can see the payload we sent, your response status and body, and how long it took. Filter by event type, status or date, search by event id, and press Resend to deliver the original payload again once you have fixed the problem. The resend goes to the endpoint's current URL and is signed with the current secret.

Test your endpoint​

Trigger a webhook.test event any time. It goes through the same signing and delivery path as real events.

curl -X POST https://sandbox.merchants.taifapay.africa/v1/webhooks/test \
-H "Authorization: Bearer $ACCESS_TOKEN"

What does not send a webhook​

Settlement decisions. Approval, rejection and payout of a settlement request push nothing today. Poll GET /v1/settlements/requests.