Skip to main content
Receive signed event notifications from Numero. Verify each signature, read the event payload and use its status fields to determine the outcome.

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 a POST 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 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

Additional events include BULK_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 are WAAS, 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 uses id, event, created_at, data and livemode. signature is a legacy nullable field; verify X-Numero-Signature instead. Fields inside data are 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 a 2xx response. For example:
The response body is optional and chosen by your application. 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 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. 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.