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.
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:
| Setting | Notes |
|---|---|
| Endpoint URL | Must be HTTPS and answer 2xx directly. Redirects are not followed, so register the final URL, trailing slash included. |
| Events | The events this endpoint receives. Leave empty to receive every notification event. |
| Description | Optional, to tell endpoints apart. |
| Active | Switch 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.
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.
| Field | Meaning |
|---|---|
id | Unique per event. Shared by every endpoint that receives it, and reused on a resend. |
eventType | The delivery type: transaction.completed, transaction.failed, transaction.settled or webhook.test. |
metadata.event | The specific, subscribable name, for example deposit.transaction.completed. |
data | The transaction. data.id is the transactionId you were given at creation. |
Headers on every delivery:
| Header | Value |
|---|---|
Content-Type | application/json |
X-Webhook-Event | The eventType, e.g. transaction.completed |
X-Webhook-Signature | sha512=<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.
- Node.js (Express)
- Python (Django)
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);
},
);
import hashlib
import hmac
import json
from django.conf import settings
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
def signature_ok(request):
header = request.headers.get("X-Webhook-Signature", "")
received = header.split("=", 1)[-1] # drop the "sha512=" prefix
expected = hmac.new(
settings.TAIFA_WEBHOOK_SECRET.encode(), request.body, hashlib.sha512
).hexdigest()
return hmac.compare_digest(received.encode(), expected.encode())
@csrf_exempt # we are not a browser, so there is no CSRF token
@require_POST
def taifa_webhook(request):
if not signature_ok(request):
return HttpResponse(status=401)
event = json.loads(request.body)
# handle event["eventType"] / event["metadata"].get("event") / event["data"] ...
return HttpResponse(status=200)
If you use the Node SDK, constructWebhookEvent() and verifyWebhookSignature() do this for you.
Handle deliveries safely
- Acknowledge fast. Return
200immediately 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 onid, 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 justeventType. A card payment sendstransaction.completedtwice, once when approved and once when settled. See card payments. - Do not fulfil from the browser. A client-side callback or
returnUrlis 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.
Related
- Webhook events: every event and its payload
- Card payments: the card event sequence
- Going live: register and test production endpoints