Webhooks

Tumia webhooks kupata sasisho za muamala kiotomatiki.

Muhtasari

Wakapay inatuma HTTP POST kwa seva yako wakati hali ya muamala inabadilika.

Hii inaepuka kuuliza mara kwa mara (polling).

Usanidi

Wasiliana na meneja wa akaunti wa Wakapay na utoe:

URL ya webhook (lazima iwe HTTPS)
Mazingira (Majaribio au Uzalishaji)
Hali ya saini (Current au Legacy)

Usalama wa Webhook

Mbinu ya Saini ya Sasa (Default)

Ili kuthibitisha saini ya webhook, utahitaji kuihesabu tena upande wako kwa kutumia vitambulisho vyako vya biashara pamoja na wakapayReference iliyotolewa katika mzigo wa webhook.

Hapa kuna utaratibu hatua kwa hatua:

Unda string katika muundo huu kamili: apiKey:apiSecret
Tengeneza hash ya SHA-256 ya string hii
Encode hash inayotokana kwa hex
Linganisha thamani uliyohesabu na sehemu ya signature iliyopokelewa katika mzigo wa webhook (Ulinganisho usio na hisia za herufi kubwa/ndogo unapendekezwa)

Mfano wa Node.js


const crypto = require("crypto");
 
function validateWebhookSignature(apiKey, apiSecret, receivedSignature) {
  const raw = `${apiKey}:${apiSecret}`;
  const expected = crypto.createHash("sha256").update(raw).digest("hex");
  return expected.toLowerCase() === (receivedSignature || "").toLowerCase();
}

Mfano wa Python


import hashlib
 
def validate_webhook_signature(api_key, api_secret, received_signature):
    raw = f"{api_key}:{api_secret}"
    expected = hashlib.sha256(raw.encode()).hexdigest()
    return expected.lower() == (received_signature or "").lower()

Mbinu ya Saini ya Legacy

Legacy tu (uunganishaji wa zamani)

Tumia tu ikiwa Wakapay imemwambia mshirika huyu autumie.

Header: X-Wakapay-Signature
Format: t=<timestamp>,v1=<hmac>

Tukio la Webhook

API ya Biashara inatumia tukio moja:

transaction.updated

Angalia status kujua hali ya sasa ya muamala.

Hali Halali za Muamala

Hali hizi tu ndizo halali kwa API ya Biashara:

termination_pending
termination_success
termination_failure

Puuza majina yote ya zamani ya hali kama completed, failed, au processing.

Muundo wa Mzigo wa Webhook


{
  "businessId": "019d487b-00a5-787a-8aec-a4e5d33689e3",
  "businessReference": "EXT-INV-2026-0001",
  "wakapayReference": "293cd2ed-2db3-11f1-8c14-0242ac120008",
  "status": "termination_success",
  "senderCurrency": "USD",
  "receiverCurrency": "KES",
  "senderAmount": 0.7751937984496124,
  "receiverAmount": 100,
  "signature": "a1b2c3d4e5f6..."
}

Sampuli za Webhooks

Mafanikio


{
  "businessId": "019d487b-00a5-787a-8aec-a4e5d33689e3",
  "businessReference": "EXT-INV-2026-0001",
  "wakapayReference": "293cd2ed-2db3-11f1-8c14-0242ac120008",
  "status": "termination_success",
  "senderCurrency": "USD",
  "receiverCurrency": "KES",
  "senderAmount": 0.7751937984496124,
  "receiverAmount": 100,
  "signature": "a1b2c3d4e5f6..."
}

Kushindwa


{
  "businessId": "019d487b-00a5-787a-8aec-a4e5d33689e3",
  "businessReference": "EXT-INV-2026-0002",
  "wakapayReference": "4f2e9c1a-8b7d-4e6f-9a0b-123456789abc",
  "status": "termination_failure",
  "senderCurrency": "USD",
  "receiverCurrency": "KES",
  "senderAmount": 0.78,
  "receiverAmount": 100,
  "signature": "..."
}

Jinsi ya Kushughulikia Webhooks

Pokea webhook
Thibitisha saini
Angalia ikiwa wakapayReference imeshashughulikiwa (kuepuka marudufu)
Sasisha muamala wako kwa kutumia businessReference
Rudisha HTTP 200 OK haraka

Ikiwa hali bado ni termination_pending, angalia muamala tena kwa kutumia GET /business/transactions/{businessReference}.

Angalia Hali ya Muamala (Wakati Bado Inasubiri)

Ikiwa hali ya webhook bado ni termination_pending, uliza muamala kupata hali ya mwisho.

Ombi


GET <BASE_URL>/business/transactions/{businessReference}

Headers:


Authorization: Bearer <business-token>

Jibu 200


{
  "wakapayReference": "019ce78b-b204-716c-95ca-737ee5ec1559",
  "businessReference": "EXT-INV-2026-0001",
  "status": "termination_success",
  "senderCurrency": "USD",
  "receiverCurrency": "KES",
  "senderAmount": 100.0,
  "receiverAmount": 13025.0,
  "createdAt": "2026-04-27T07:10:00Z",
  "updatedAt": "2026-04-27T07:12:10Z"
}

Jibu 404


{
  "error": "transaction not found"
}

Mbinu Bora

Thibitisha saini kabla ya kushughulikia
Shughulikia uwasilishaji wa marudufu kwa kutumia wakapayReference
Rudisha 200 OK haraka
Tumia HTTPS tu
Weka kumbukumbu kwa utatuzi

Utatuzi wa Matatizo

Uthibitishaji wa saini umeshindwa

Tumia apiKey na apiSecret sahihi
Muundo wa string lazima uwe apiKey:apiSecret kabisa
Tumia SHA-256
Linganisha bila kujali herufi kubwa/ndogo

Webhook haijapokelewa

Angalia kiungo (endpoint) ni cha umma
Angalia cheti halali cha HTTPS
Thibitisha URL na meneja wa akaunti wa Wakapay

Marudio mengi/timeouts

Rudisha 200 OK haraka
Hamishia kazi nzito kwenye foleni ya nyuma