Webhooks

Numero originates every webhook: we decide which events fire, when (including on failure), the exact payload, and the signature. Your integration is a pure receiver — verify the signature, read the fields, branch on status.

Setting up webhooks

Configure your webhook URL in the Merchant Dashboard → Settings → Developer → Webhooks:

Add your webhook endpoint URL
Select the events you want (or subscribe to all with "*")
Your signing secret is generated — save it securely (you can view it again anytime via a verification code)

Your signing secret verifies that incoming webhooks are genuinely from Numero. Keep it private and never expose it in client-side code.

How webhooks work

An event occurs       →  e.g., a customer funds your virtual account
Numero sends a POST   →  We POST a JSON payload to your webhook URL
You verify & process  →  Verify the signature, process the event, return 2xx

Envelope

Every delivery is a POST of this structure:

{
  "id": "f0c3a1b2-...",
  "event": "FUNDING_NOTIFICATION",
  "created_at": "2026-06-16T10:30:00Z",
  "data": { }
}

Field	Type	Description
`id`	string	Unique delivery id — use it to dedupe (the same event may arrive more than once)
`event`	string	The event type (see below)
`created_at`	string	ISO 8601 timestamp
`data`	object	Event-specific payload (schemas below)

The envelope and data use the API’s camelCase field names.

Headers

Header	Description
`Content-Type`	`application/json`
`X-Numero-Signature`	`t=<timestamp>,v1=<base64 HMAC-SHA256>` — see Signature Verification
`X-Webhook-Id`	Unique delivery id (also in the body as `id`)
`X-Webhook-Event`	The event type

Event types

Event	Fires on	Success	Failure	`data` schema
`FUNDING_NOTIFICATION`	Inbound credit lands (VA funding, settlement) and internal-transfer receipt	✓	n/a¹	`TransactionWebhookData`
`TRANSFER_NOTIFICATION`	Outbound bank transfer settles and internal-transfer send	✓	✓	`TransactionWebhookData`
`PAYOUT_NOTIFICATION`	International payout settles	✓	✓	`TransactionWebhookData`
`BILLS_PURCHASE_NOTIFICATION`	A bill payment (airtime/data/electricity/cable/betting) settles	✓	✓	`BillsPurchaseWebhook`
`VERIFICATION_NOTIFICATION`	A verification settles out of Pending	✓	✓	`VerificationWebhookData`
`VIRTUAL_ACCOUNT_CREATED`	A customer/business virtual account is minted	✓	n/a²	`VirtualAccountCreatedData`
`CURRENCY_CONVERSION`	An FX conversion completes	✓	n/a²	`CurrencyConversionData`

¹ An inbound credit has no “merchant failure” to report. ² FX conversion and VA creation are synchronous — a failure is returned in the API response (status: false + a 4xx/503), so there’s nothing to webhook. Branch on the call’s own response for those.

Determine the outcome from data.status (Successful / Unsuccessful / Pending) and data.requestState / data.requestStateDetails — don’t infer it from the event type. A failed outbound transfer/payout fires with status: "Unsuccessful" and requestState: "Failed"; the debit is returned to your wallet through the reversal workflow.

Payloads

`TransactionWebhookData` — money movement (transfer / funding / payout / internal)

All amounts are in naira.

{
  "reference": "TRF-20260616-abc123",
  "type": "Transfer",
  "service": "SingleTransfer",
  "direction": "DEBIT",
  "status": "Successful",
  "requestState": "Completed",
  "requestStateDetails": "Transfer completed successfully",
  "currency": "NGN",
  "trxAmount": 50000.00,
  "trxFee": 25.00,
  "stampDutyApplied": true,
  "stampDutyAmount": 50.00,
  "balanceBefore": 120000.00,
  "balanceAfter": 69925.00,
  "toAccountName": "Jane Smith",
  "toAccountNumber": "0123456789",
  "toAccountBank": "GT Bank",
  "merchant": "Your Business Name",
  "businessCode": "BUS001",
  "isReversed": false,
  "token": null,
  "dateCreated": "2026-06-16T10:30:00Z",
  "dateModified": "2026-06-16T10:30:05Z"
}

Field	Type	Description
`reference`	string	Transaction reference
`type` / `service`	string	Transaction type and service
`direction`	string	`CREDIT` or `DEBIT`
`status`	string	`Successful` · `Unsuccessful` · `Pending`
`requestState` / `requestStateDetails`	string	Processing state + detail
`trxAmount`	number	Amount (naira)
`trxFee`	number	The fee charged on this transaction (naira)
`stampDutyApplied` / `stampDutyAmount`	bool / number	Stamp duty, when applicable
`balanceBefore` / `balanceAfter`	number	Wallet balance around the event
`beneficiaryName` / `beneficiaryNumber` / `beneficiaryBank`	string	The payer (on credits)
`toAccountName` / `toAccountNumber` / `toAccountBank`	string	The recipient (on debits)
`merchant` / `businessCode`	string	Your business
`isReversed`	bool	Whether the transaction was reversed
`token`	string	Utility token, when applicable
`dateCreated` / `dateModified`	string	Timestamps

`BillsPurchaseWebhook` — VAS

{
  "businessCode": "BUS001",
  "vertical": "ELECTRICITY",
  "reference": "BILL-20260616-abc123",
  "status": "Successful",
  "amount": 5000.00,
  "customerIdentifier": "04223456789",
  "message": "Token generated",
  "token": "1234-5678-9012-3456"
}

Field	Type	Description
`vertical`	string	`AIRTIME` · `DATA` · `ELECTRICITY` · `CABLETV` · `BETTING`
`status`	string	`Successful` · `Failed`
`customerIdentifier`	string	Phone / meter / smartcard / betting id
`token`	string	Utility token (electricity), when applicable

`VerificationWebhookData`

{
  "businessCode": "BUS001",
  "reference": "VER-20260616-abc123",
  "type": "BVN",
  "status": "Completed",
  "businessCharge": 50.00,
  "statusCode": "00",
  "statusMessage": "Verification successful"
}

Field	Type	Description
`type`	string	e.g. `BVN`, `NIN`, `CAC_ADVANCED`
`status`	string	`Completed` · `Failed`
`businessCharge`	number	Naira charged (null if not charged)

`VirtualAccountCreatedData`

{
  "businessCode": "BUS001",
  "reference": "VA-20260616-abc123",
  "accountNumber": "8012345678",
  "accountName": "John Doe",
  "bankName": "...",
  "customerEmail": "[email protected]",
  "type": "customer"
}

Field	Type	Description
`type`	string	`customer` or `business`
`customerEmail`	string	null for business VAs

`CurrencyConversionData`

{
  "businessCode": "BUS001",
  "reference": "FX-20260616-abc123",
  "fromCurrency": "NGN",
  "toCurrency": "USD",
  "fromAmount": 1600000.00,
  "toAmount": 1000.00,
  "rate": 1600.00,
  "status": "Successful"
}

Field casing. The four envelope fields are exactly id, event, created_at and data — note created_at is snake_case. Everything inside data is camelCase, matching the rest of the API.

Retries

Respond 2xx to acknowledge. Any non-2xx (or a timeout) is a failed delivery.
Every webhook is persisted before delivery, so events are never lost if your endpoint is down.
Failed deliveries are retried automatically with exponential backoff for up to 24 hours, and can be re-sent manually from the dashboard. After 10 consecutive failures the subscription is disabled.
Webhook delivery never affects the transaction it describes. A failed or refused delivery does not reverse, hold or retry the underlying money movement — treat the webhook as notification, and the transaction status endpoint as the source of truth.

Getting Started

Transfers & Payouts

Collections (Virtual Accounts)

Wallet-as-a-Service

Customers

Invoices

Cards

Cardholders

Balance & Transactions

Value Added Services

Credit

Verification / KYC

Webhooks

Setting up webhooks

How webhooks work

Envelope

Headers

Event types

Payloads

`TransactionWebhookData` — money movement (transfer / funding / payout / internal)

`BillsPurchaseWebhook` — VAS

`VerificationWebhookData`

`VirtualAccountCreatedData`

`CurrencyConversionData`

Retries

​Setting up webhooks

​How webhooks work

​Envelope

​Headers

​Event types

​Payloads

​TransactionWebhookData — money movement (transfer / funding / payout / internal)

​BillsPurchaseWebhook — VAS

​VerificationWebhookData

​VirtualAccountCreatedData

​CurrencyConversionData

​Retries

Setting up webhooks

How webhooks work

Envelope

Headers

Event types

Payloads

`TransactionWebhookData` — money movement (transfer / funding / payout / internal)

`BillsPurchaseWebhook` — VAS

`VerificationWebhookData`

`VirtualAccountCreatedData`

`CurrencyConversionData`

Retries