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 and secure delivery requirements.
A webhook subscription contains your HTTPS endpoint URL, selected event types and a signing secret. Configure separate subscriptions for Test and Live events. Store the signing secret securely and use it to verify every delivery.
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
Envelope
Every delivery is aPOST of this structure:
The envelope and
data use the API’s camelCase field names.
Headers
Event types
¹ 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 fromdata.status(Successful/Unsuccessful/Pending) anddata.requestState/data.requestStateDetails— don’t infer it from the event type. A failed outbound transfer/payout fires withstatus: "Unsuccessful"andrequestState: "Failed"; the debit is returned to your wallet through the reversal workflow.
Payloads
Additional subscription events
Additional events includeBULK_TRANSFER_NOTIFICATION for terminal bulk-transfer batch outcomes and these WAAS events:
Event names are case-sensitive and are the same in Test and Live mode. A
WAAS subscription includes all WAAS events. Exact-event subscriptions and * are also supported. VIRTUAL_ACCOUNT_RETIRED is reserved and is not currently emitted.
Service groups
The subscription groups areWAAS, VIRTUAL_CARDS, INVOICES, FUNDING, TRANSFERS, BILLS, DIGITAL, 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 notifications are asynchronous. Pending card requests do not emit successful creation or funding events. Payloads include transaction references, status, currency and relevant amounts or balances; they exclude 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.
Use the test-event endpoint to check your receiver. 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)
Amounts use the currency in the payload. Domestic money movements normally use NGN.
BillsPurchaseWebhook — VAS
DigitalPurchaseWebhook — Digital
Select Digital in webhook settings, or subscribe to DIGITAL / DIGITAL_PURCHASE_NOTIFICATION.
It covers GLOBALAIRTIME, GLOBALDATA, GIFTCARD and UTILITY. Pending is provisional; wait for
Successful or Failed, or poll the transaction status endpoint. An immediate rejection before a
purchase is recorded is returned by the purchase API and does not imply a webhook will follow.
A complete delivery to your server looks like this:
amount is the purchase principal in the stated currency; the quoted service fee is separate.
Gift-card codes and other delivery credentials are excluded: retrieve them from the authenticated
Digital delivery endpoint after successful fulfilment.
Existing BILLS or BILLS_PURCHASE_NOTIFICATION subscriptions continue to receive Digital purchases
with their original event name. Selecting Digital opts that subscription into the new event name.
A subscription selecting both groups, or *, gets one Digital event per emitted status, not both names.
Retries preserve that choice. This does not replay purchases from before the subscription change.
Test with eventType: "DIGITAL_PURCHASE_NOTIFICATION" at the test-event endpoint.
The synthetic sample carries isSample: true and purchases no product.
VerificationWebhookData
VirtualAccountCreatedData
CurrencyConversionData
Field casing. The envelope usesid,event,created_at,dataandlivemode.signatureis a legacy nullable field; verifyX-Numero-Signatureinstead. Fields insidedataare camelCase.
Your receiver’s response
The JSON above is the notification request body sent to your server. After verifying the signature and durably accepting the event, your server acknowledges it with a2xx response. For example:
204 No Content also acknowledges the
event. Numero does not return a separate transaction response to a webhook receiver; retrieve current
transaction or delivery details using the corresponding authenticated API endpoint. An acknowledgement
does not change the purchase status or prove fulfilment.
Retries
- Respond
2xxto 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. 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.