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

For API-issued cards, the Virtual Cards group includes private wallet verification codes (card.code). See Card wallet verification for the payload, source-based delivery routing and sensitive-code handling requirements. Configure your webhook URL in the Merchant Dashboard → Settings → Developer → Webhooks:

Add your webhook endpoint URL
Select the services you want. Each checkbox includes every event in that service; individual-event selection is not offered in the dashboard.
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

Additional subscription events

The dashboard also offers BULK_TRANSFER_NOTIFICATION for terminal bulk-transfer batch outcomes and these WAAS events:

Event	Meaning
`customer_wallet.created`	Customer wallet created
`customer_wallet.virtual_account_attached`	Virtual account linked to the wallet
`customer_wallet.credited`	Customer wallet credited; merchant-pool settlement can still be pending
`customer_wallet.debited`	Customer wallet debited
`customer_wallet.transfer`	Transfer between customer wallets completed
`customer_wallet.payout.pending`	Customer payout pending, not a final outcome
`customer_wallet.payout.sent`	Customer payout sent successfully
`customer_wallet.payout.failed`	Customer payout failed
`customer.kyc_updated`	Customer KYC status changed

These exact, case-sensitive names identify delivered events in both live and test mode. Select WAAS in the dashboard to include every WAAS event. Existing subscriptions retain their selections until you save changes; saving an older individual-event subscription upgrades the selected services to whole groups. Existing API integrations using exact event names or * remain supported. VIRTUAL_ACCOUNT_RETIRED remains reserved and is not currently emitted.

Service groups

The subscription groups are WAAS, VIRTUAL_CARDS, INVOICES, FUNDING, TRANSFERS, BILLS, VERIFICATIONS, VIRTUAL_ACCOUNTS, PAYOUTS and FX. Selecting a group includes its events, including future events in that service. Service availability and access requirements still apply. Virtual Cards includes card.created, card.creation_failed, card.funded, card.funding_failed, card.withdrawn, card.withdrawal_failed, card.frozen, card.unfrozen, card.terminated, card.authorization, card.payment, card.refund, card.reversal and card.declined. Closing a card is termination, not deletion of its transaction history. Invoices includes invoice.created, invoice.updated, invoice.partially_paid, invoice.paid, invoice.cancelled and invoice.expired. These events report recorded lifecycle changes; a due date passing alone is not a payment or a recorded expiry. Card and invoice lifecycle events are queued in the same database transaction as their source changes, then delivered by the background worker (normally on its next minute cycle). Pending card requests do not emit successful creation or funding events. The payload contains customer-facing references, status, currency and relevant amounts or balances—never card credentials. Use data.eventId to deduplicate card and invoice lifecycle events; it stays stable across delivery retries. Delivery is at least once, so a retry may reach an endpoint that previously accepted the event. A test event goes only to test subscriptions, including on retry. The dashboard’s Send test event lets you choose a service. Synthetic non-funding samples carry isSample: true and do not create a real card, invoice or wallet transaction.

`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

Additional subscription events

Service groups

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

`BillsPurchaseWebhook` — VAS

`VerificationWebhookData`

`VirtualAccountCreatedData`

`CurrencyConversionData`

Retries

​Setting up webhooks

​How webhooks work

​Envelope

​Headers

​Event types

​Payloads

​Additional subscription events

​Service groups

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

​BillsPurchaseWebhook — VAS

​VerificationWebhookData

​VirtualAccountCreatedData

​CurrencyConversionData

​Retries

Setting up webhooks

How webhooks work

Envelope

Headers

Event types

Payloads

Additional subscription events

Service groups

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

`BillsPurchaseWebhook` — VAS

`VerificationWebhookData`

`VirtualAccountCreatedData`

`CurrencyConversionData`

Retries