Webhook Implementation

Overview: WaaS sends real-time transaction notifications to your registered webhook URL. You must implement a secure, publicly accessible endpoint.

Webhook URL Requirements

Protocol: HTTPS only

Accessibility: Publicly reachable (not localhost)

Port: 443 (standard HTTPS)

Method: POST

Response Time: ≤ 2 seconds

Format: JSON

Example Valid URLs:

https://api.yourcompany.com/v1/waas/webhook

https://webhooks.yourdomain.com/transactions

Webhook Registration

1. Develop webhook endpoint meeting specifications
2. Test with sample payloads
3. Contact us with webhook URL

Webhook Request Format

Request Parameters

POST

curl -X POST
  -H "Content-Type: application/json"
  -d '{
      "walletNumber": "80998899834",
      "transactionType": "Credit",
      "senderAccountNumber": "0023456789",
      "senderBankCode": "058",
      "transactionReference": "TXN_20240115_123456",
      "senderName": "John Mark",
      "amount": 8000.00,
      "balance": 900000.09,
      "narration": "Salary Payment January 2024"
  }
'

Required Webhook Response

Sample Success Response

POST

{
  "responseCode": "00",
  "responseDescription": "Record Processed Successfully"
}

Sample Request

Request Parameters

Field	Type	Description	Example
walletNumber	string	Recipient wallet number	"80998899834"
transactionType	string	"Credit" or "Debit"	"Credit"
senderAccountNumber	string	Sender account (if bank transfer)"	"0023456789"
senderBankCode	string	Sender bank code	"058" (GTBank)See Bank code Dictionary
transactionReference	string	Unique transaction reference	"TXN_20240115_123456"
senderName	string	Sender/initiator name	"John Mark"
amount	number	Transaction amount	8000.00
balance	number	New wallet balance	900000.09
narration	string	Transaction description	"Salary Payment"

Sample Response

Response Parameters

Code	Description	When to use
00	Success	Webhook received the request