Webhook Notifications

Introduction

Welcome to the Numero Webhook API documentation. This guide explains how to integrate with our webhook system to receive real-time notifications about events occurring within the Numero platform.

Webhooks allow your application to receive push notifications when specific events happen, eliminating the need to poll our API for updates. This results in more efficient integrations and real-time data synchronization.

Getting Started

Prerequisites

A Numero account with API access

A publicly accessible HTTPS endpoint to receive webhook events

Basic understanding of HTTP requests and JSON

Authentication

All webhook management endpoints require authentication using your Numero API key. Include your API key in the Authorization header:

Webhook Subscription Management

Creating a Webhook Subscription

To start receiving webhook notifications, you need to create a webhook subscription.

Endpoint: POST /api/v1/webhook/subscriptions

Request Body:

{
  "url": "[https://your-domain.com/webhook-endpoint](https://your-domain.com/webhook-endpoint)",
  "eventTypes": ["FUNDING_NOTIFICATION", "TRANSFER_NOTIFICATION"],
  "description": "Production webhook for payment notifications"
}

Parameters:

Parameter	Type	Required	Description
`url`	string	Yes	The HTTPS URL where webhook events will be sent
`eventTypes`	array	Yes	Array of event types to subscribe to
`description`	string	No	Optional description for this webhook

Response:

{
  "id": "wh_123456789",
  "url": "[https://your-domain.com/webhook-endpoint](https://your-domain.com/webhook-endpoint)",
  "secret": "whsec_abcdefghijklmnopqrstuvwxyz123456789",
  "isActive": true,
  "description": "Production webhook for payment notifications",
  "eventTypes": ["FUNDING_NOTIFICATION", "TRANSFER_NOTIFICATION"],
  "createdAt": "2023-03-15T14:30:45Z",
  "lastSuccessfulDelivery": null
}

Important: Store the secret value securely. It will only be shown once and is required to verify webhook signatures.

Listing Webhook Subscriptions

Retrieve all webhook subscriptions for your account.

Endpoint: GET /api/v1/webhook/subscriptions

Response:

[
  {
    "id": "wh_123456789",
    "url": "[https://your-domain.com/webhook-endpoint](https://your-domain.com/webhook-endpoint)",
    "isActive": true,
    "description": "Production webhook for payment notifications",
    "eventTypes": ["FUNDING_NOTIFICATION", "TRANSFER_NOTIFICATION"],
    "createdAt": "2023-03-15T14:30:45Z",
    "lastSuccessfulDelivery": "2023-03-15T15:42:12Z"
  }
]

Updating a Webhook Subscription

Update an existing webhook subscription.

Endpoint: PUT /api/v1/webhook/subscriptions/{id}

Request Body:

{
  "url": "[https://your-domain.com/new-webhook-endpoint](https://your-domain.com/new-webhook-endpoint)",
  "eventTypes": ["FUNDING_NOTIFICATION", "TRANSFER_NOTIFICATION"],
  "description": "Updated webhook endpoint"
}

Deleting a Webhook Subscription

Delete a webhook subscription when you no longer want to receive notifications.

Endpoint: DELETE /api/v1/webhook/subscriptions/{id}

Response:

{
  "success": true
}

Regenerating a Webhook Secret

If your webhook secret is compromised, you can generate a new one.

Endpoint: POST /api/v1/webhook/subscriptions/{id}/regenerate-secret

Response: Same as the create subscription response, but with a new secret.

Supported Event Types

Numero supports the following event types:

Event Type	Description
`FUNDING_NOTIFICATION`	Triggered when your account is funded
`TRANSFER_NOTIFICATION`	Triggered when a transfer is completed
`PAYOUT_NOTIFICATION`	Triggered when a payout is completed

Note: To subscribe to all event types, include "*" in your eventTypes array.

Receiving Webhooks

Webhook Payload Format

When an event occurs, Numero will send an HTTP POST request to your webhook URL.

Example Payload (Generic):

{
  "id": "evt_123456789",
  "event": "PAYOUT_NOTIFICATION",
  "created_at": "2023-03-15T15:42:12Z",
  "data": {
    "transaction_id": "txn_987654321",
    "amount": 5000.00,
    "currency": "NGN",
    "status": "completed",
    "customer_id": "cus_12345",
    "description": "Payment for invoice #12345"
  },
  "signature": "V1tjDjfxTC2ZM+wnYGD1lGCHJGuK9bHxDXG/..."
}

Example Payload (Transfer Notification):

{
  "Id": "9de79979-2777-4c6c-8139-f01de56668ed",
  "Event": "TRANSFER_NOTIFICATION",
  "CreatedAt": "2025-07-10T05:10:55.417772Z",
  "Data": {
     "TrxAmount": 1000.0,
     "TrxFee": 40.00,
     "SettledAmount": 1000.0,
     "Merchant": "Smallville1 Limited",
     "BusinessCode": "10984212",
     "Reference": "T489820257477",
     "SessionId": "000017241015102917082338359602",
     "VendorReference": "BLSTRSFM2A8REZ2B9R1HXYAJH9",
     "Type": "FundTransfer",
     "Status": "Successful",
     "Channel": "Web",
     "PostingType": "Dr",
     "Description": "test",
     "Service": "FUNDTRANSFER",
     "RequestState": "Completed",
     "RequestStateDetails": "Completed",
     "BeneficiaryName": "John Doe",
     "BeneficiaryNumber": "3121894268",
     "BeneficiaryBank": "FIRST BANK OF NIGERIA",
     "DateCreated": "2025-07-10T05:10:54.313692",
     "DateModified": "2025-07-10T05:10:55.4087666+00:00"
  },
  "Signature": "4IrGq6x8FoVFYDO267G08Zb0nDwDypiY41/..."
 }

Field Descriptions:

Field	Description
`id`	Unique identifier for this webhook event
`event`	The type of event that triggered this webhook
`created_at`	ISO 8601 timestamp when the event occurred
`data`	Event-specific payload data
`signature`	Signature for verifying the webhook authenticity

Webhook Headers

Each webhook request includes the following HTTP headers:

Header	Description
`Content-Type`	Always `application/json`
`X-Webhook-Signature`	The signature used to verify the payload
`X-Webhook-Id`	The unique ID of the webhook event
`X-Webhook-Event`	The type of event

Security: Verifying Webhooks

To ensure that webhook requests are genuinely from Numero and haven't been tampered with, you should verify the signature of each webhook.

Verification Process

Extract the signature from the X-Webhook-Signature header.

Compute an HMAC-SHA256 signature of the raw request body using your webhook secret.

Compare the computed signature with the received signature.

Code Examples

Node.js

PHP

Python

Best Practices

Webhook Implementation

Respond quickly: Your webhook endpoint should acknowledge receipt of the webhook by returning a 2xx HTTP status code as quickly as possible, ideally within 5 seconds.

Process asynchronously: Handle the actual processing of the webhook data asynchronously after acknowledging receipt.

Implement idempotency: Webhooks may occasionally be delivered more than once. Design your webhook handler to be idempotent (producing the same result even if called multiple times).

Always verify signatures: Never skip signature verification in production environments.

Use HTTPS: Your webhook endpoint must use HTTPS to ensure secure transmission of data.

Error Handling

Retry mechanism: Numero will retry failed webhook deliveries with an exponential backoff schedule for up to 24 hours.

Monitor failures: If a webhook subscription fails consistently, it will be automatically disabled after 10 consecutive failures.

Webhook logs: Use the webhook dashboard to monitor delivery status and troubleshoot issues.

Troubleshooting

Common Issues

Webhook not being received:

Verify your endpoint is publicly accessible.

Check that your server is correctly configured to accept POST requests.

Ensure your firewall isn't blocking our webhook requests.

Signature verification fails:

Confirm you're using the correct webhook secret.

Ensure you're verifying against the raw request body.

Check that you're using the correct hashing algorithm (HMAC-SHA256).

Webhook disabled:

If your endpoint fails to respond with a 2xx status code for 10 consecutive attempts, the webhook will be automatically disabled.

You can reactivate it through the API or dashboard.

Getting Help

If you encounter issues with webhooks that you can't resolve, please contact our support team at engineering@usenumero.com with the following information:

Your webhook subscription ID.

Any error messages you're receiving.

Steps you've taken to troubleshoot.

Rate Limits and Quotas

Webhook delivery attempts: Limited to 25 requests per second per account.

Webhook management API endpoints: Limited to 100 requests per minute per account.

Introduction#

Getting Started#

Prerequisites#

Authentication#

Webhook Subscription Management#

Creating a Webhook Subscription#

Listing Webhook Subscriptions#

Updating a Webhook Subscription#

Deleting a Webhook Subscription#

Regenerating a Webhook Secret#

Supported Event Types#

Receiving Webhooks#

Webhook Payload Format#

Webhook Headers#

Security: Verifying Webhooks#

Verification Process#

Code Examples#

Best Practices#

Webhook Implementation#

Error Handling#

Troubleshooting#

Common Issues#

Getting Help#

Rate Limits and Quotas#

Introduction

Getting Started

Prerequisites

Authentication

Webhook Subscription Management

Creating a Webhook Subscription

Listing Webhook Subscriptions

Updating a Webhook Subscription

Deleting a Webhook Subscription

Regenerating a Webhook Secret

Supported Event Types

Receiving Webhooks

Webhook Payload Format

Webhook Headers

Security: Verifying Webhooks

Verification Process

Code Examples

Best Practices

Webhook Implementation

Error Handling

Troubleshooting

Common Issues

Getting Help

Rate Limits and Quotas