Webhooks

Configure webhook URLs from the business dashboard. These URLs are used for Rivo Business event delivery once outbound webhook dispatch is enabled for your integration.

Current rollout note

Webhook URL management is available today. Before relying on live partner webhook events, confirm with Rivo that outbound delivery has been enabled for the event types you need.

Manage webhook URLs

Webhook management uses the business dashboard JWT flow, not API-key signing.

Create webhook

POST /business/v1/webhooks
Authorization: Bearer BUSINESS_DASHBOARD_JWT
Content-Type: application/json

{
  "targetUrl": "https://merchant.example.com/rivo/webhooks"
}

targetUrl must be a valid http or https URL. Duplicate URLs for the same business are rejected. Example response:

{
  "status": "success",
  "message": "Webhook added successfully",
  "data": {
    "_id": "6a51a0000000000000000001",
    "businessId": "69f13c6445e423d22696ad09",
    "targetUrl": "https://merchant.example.com/rivo/webhooks",
    "secret": "whsec_example",
    "createdAt": "2026-07-11T01:40:00.000Z",
    "updatedAt": "2026-07-11T01:40:00.000Z"
  }
}

List webhooks

GET /business/v1/webhooks
Authorization: Bearer BUSINESS_DASHBOARD_JWT

Example response:

{
  "status": "success",
  "message": "Webhooks retrieved successfully",
  "data": [
    {
      "_id": "6a51a0000000000000000001",
      "businessId": "69f13c6445e423d22696ad09",
      "targetUrl": "https://merchant.example.com/rivo/webhooks",
      "secret": "whsec_example",
      "createdAt": "2026-07-11T01:40:00.000Z",
      "updatedAt": "2026-07-11T01:40:00.000Z"
    }
  ]
}

Delete webhook

DELETE /business/v1/webhooks/{id}
Authorization: Bearer BUSINESS_DASHBOARD_JWT

Example response:

{
  "status": "success",
  "message": "Webhook deleted successfully",
  "data": {}
}

Delivery format

Every webhook is an HTTP POST to your targetUrl with a JSON body in this envelope:

{
  "event": "transfer.completed",
  "data": {}
}

Field	Meaning
`event`	Event name, for example `payment.completed`. Use it to route the payload.
`data`	The resource the event is about. Its shape depends on the event and is documented below.

Headers:

Content-Type: application/json
x-webhook-signature: <hex HMAC-SHA512 of the request body, keyed with your webhook secret>

Rivo waits up to 5 seconds for a response. Return a 2xx status once you have stored the event. Process it asynchronously if handling takes longer. Events can arrive more than once and out of order. Deduplicate using the event name plus the resource reference (or id), and always treat the latest status you read from the API as the source of truth.

Verify the signature

Compute an HMAC-SHA512 of the raw request body using your webhook secret and compare it with the x-webhook-signature header before trusting the payload.

import crypto from "crypto";

export function isValidRivoWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha512", secret)
    .update(rawBody)
    .digest("hex");

  return (
    typeof signature === "string" &&
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
  );
}

Use the raw body exactly as received. Re-serializing parsed JSON can change the bytes and break verification.

Events

Event	Sent when
`payment.created`	A payment checkout is initiated.
`payment.completed`	The customer pays a checkout in full.
`payment.failed`	A checkout fails or expires without full payment.
`payment_link.created`	A payment link is created.
`payment_link.paid`	A payment is received on a payment link.
`payment_link.expired`	A payment link expires or is expired manually.
`transfer.created`	An NGN transfer is accepted and queued.
`transfer.completed`	The NGN transfer is paid out to the recipient bank account.
`transfer.failed`	The NGN transfer fails.
`virtual-account.created`	A customer virtual account is ready to receive funds.
`virtual-account.rejected`	A customer virtual account request is rejected.

payment.created

Sent after POST /payments/initiate succeeds.

{
  "event": "payment.created",
  "data": {
    "id": "6a51a0000000000000000101",
    "reference": "my_custom_ref_123",
    "code": "abc123def456",
    "link": "https://payment.userivo.co/checkout/abc123def456",
    "amount": 50000,
    "currency": "NGN",
    "status": "pending",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "redirectUrl": "https://example.com/payment-success",
    "expiresAt": "2026-07-10T13:00:00.000Z",
    "createdAt": "2026-07-10T12:00:00.000Z"
  }
}

payment.completed

Sent when the checkout is paid in full. amountSettled is what reaches your balance after fee.

{
  "event": "payment.completed",
  "data": {
    "id": "6a51a0000000000000000101",
    "reference": "my_custom_ref_123",
    "code": "abc123def456",
    "amount": 50000,
    "amountPaid": 50000,
    "fee": 500,
    "amountSettled": 49500,
    "currency": "NGN",
    "status": "completed",
    "channel": "bank_transfer",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "paidAt": "2026-07-10T12:05:00.000Z",
    "createdAt": "2026-07-10T12:00:00.000Z",
    "updatedAt": "2026-07-10T12:05:00.000Z"
  }
}

payment.failed

Sent when a checkout fails or expires before full payment. reason explains why.

{
  "event": "payment.failed",
  "data": {
    "id": "6a51a0000000000000000101",
    "reference": "my_custom_ref_123",
    "code": "abc123def456",
    "amount": 50000,
    "amountPaid": 0,
    "currency": "NGN",
    "status": "failed",
    "reason": "Checkout expired before payment",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "createdAt": "2026-07-10T12:00:00.000Z",
    "updatedAt": "2026-07-10T13:00:00.000Z"
  }
}

payment_link.created

Sent after POST /payment-links succeeds. data is the payment link.

{
  "event": "payment_link.created",
  "data": {
    "id": "64b2c1234567890",
    "code": "xyz789abc012",
    "title": "Invoice 1001",
    "description": "Customer invoice",
    "amount": 25000,
    "currency": "naira",
    "type": "fiat",
    "status": "pending",
    "isExactAmount": true,
    "metadata": {
      "partnerReference": "invoice-1001"
    },
    "expiresAt": "2026-07-11T12:00:00.000Z",
    "createdAt": "2026-07-10T12:00:00.000Z"
  }
}

payment_link.paid

Sent when a payment is received on a payment link. data is the payment link, with the received payment under payment.

{
  "event": "payment_link.paid",
  "data": {
    "id": "64b2c1234567890",
    "code": "xyz789abc012",
    "title": "Invoice 1001",
    "amount": 25000,
    "currency": "naira",
    "type": "fiat",
    "status": "completed",
    "metadata": {
      "partnerReference": "invoice-1001"
    },
    "payment": {
      "reference": "6a51a0000000000000000201",
      "amount": 25000,
      "fee": 250,
      "amountSettled": 24750,
      "currency": "NGN",
      "sender": {
        "accountName": "JANE DOE",
        "accountNumber": "0123456789",
        "bankName": "Access Bank"
      },
      "paidAt": "2026-07-10T14:00:00.000Z"
    },
    "expiresAt": "2026-07-11T12:00:00.000Z",
    "createdAt": "2026-07-10T12:00:00.000Z",
    "updatedAt": "2026-07-10T14:00:00.000Z"
  }
}

For crypto links, payment.sender is replaced by payment.cryptoSender with the sending address, and the payment includes network and transactionHash.

payment_link.expired

Sent when a payment link expires, including when you call POST /payment-links/{id}/expire.

{
  "event": "payment_link.expired",
  "data": {
    "id": "64b2c1234567890",
    "code": "xyz789abc012",
    "title": "Invoice 1001",
    "amount": 25000,
    "currency": "naira",
    "type": "fiat",
    "status": "expired",
    "isActive": false,
    "metadata": {
      "partnerReference": "invoice-1001"
    },
    "expiresAt": "2026-07-11T12:00:00.000Z",
    "createdAt": "2026-07-10T12:00:00.000Z",
    "updatedAt": "2026-07-11T12:00:00.000Z"
  }
}

transfer.created

Sent after POST /transfers/ngn accepts and queues a transfer. data has the same shape as GET /transfers/ngn/{reference}.

{
  "event": "transfer.created",
  "data": {
    "id": "64b2c1234567890",
    "reference": "txn_123456",
    "amount": 1000,
    "fee": 50,
    "currency": "NGN",
    "type": "transfer",
    "status": "queued",
    "narration": "Payment for services",
    "accountDetails": {
      "accountNumber": "0123456789",
      "accountName": "JOHN DOE",
      "bankName": "Access Bank"
    },
    "createdAt": "2026-07-10T12:00:00.000Z",
    "updatedAt": "2026-07-10T12:00:00.000Z"
  }
}

transfer.completed

Sent when the recipient bank account has been paid.

{
  "event": "transfer.completed",
  "data": {
    "id": "64b2c1234567890",
    "reference": "txn_123456",
    "amount": 1000,
    "fee": 50,
    "currency": "NGN",
    "type": "transfer",
    "status": "successful",
    "narration": "Payment for services",
    "accountDetails": {
      "accountNumber": "0123456789",
      "accountName": "JOHN DOE",
      "bankName": "Access Bank"
    },
    "completedAt": "2026-07-10T12:01:00.000Z",
    "createdAt": "2026-07-10T12:00:00.000Z",
    "updatedAt": "2026-07-10T12:01:00.000Z"
  }
}

transfer.failed

Sent when the transfer cannot be completed. reason explains why. Debited funds are returned to your balance.

{
  "event": "transfer.failed",
  "data": {
    "id": "64b2c1234567890",
    "reference": "txn_123456",
    "amount": 1000,
    "fee": 50,
    "currency": "NGN",
    "type": "transfer",
    "status": "failed",
    "reason": "Beneficiary bank unavailable",
    "narration": "Payment for services",
    "accountDetails": {
      "accountNumber": "0123456789",
      "accountName": "JOHN DOE",
      "bankName": "Access Bank"
    },
    "createdAt": "2026-07-10T12:00:00.000Z",
    "updatedAt": "2026-07-10T12:03:00.000Z"
  }
}

virtual-account.created

Sent when a customer virtual account is ready to receive funds. data has the same shape as the matching GET /virtual-accounts/... response, plus currency. NGN account:

{
  "event": "virtual-account.created",
  "data": {
    "accountNumber": "9912345678",
    "accountName": "Jane Doe",
    "bankName": "Rivo Bank",
    "reference": "ref_perm_123",
    "type": "permanent",
    "status": "active",
    "currency": "NGN"
  }
}

Temporary NGN accounts also include expiresAt. USD account:

{
  "event": "virtual-account.created",
  "data": {
    "paymentRails": ["ach", "wire"],
    "id": "64b2c1234567890",
    "reference": "ref_usd_123",
    "status": "active",
    "bankName": "Bridge Bank / Evolve Bank & Trust",
    "bankAddress": "6000 Poplar Ave, Memphis, TN 38119, United States",
    "bankBeneficiaryName": "John Doe",
    "bankBeneficiaryAddress": "123 Business St, Suite 100, Wilmington, DE 19801",
    "bankAccountNumber": "123456789012",
    "bankRoutingNumber": "084000026",
    "currency": "USD",
    "createdAt": "2026-03-01T10:00:00.000Z",
    "updatedAt": "2026-03-01T10:00:00.000Z"
  }
}

virtual-account.rejected

Sent when a virtual account request is rejected, for example when customer verification fails. reason explains why. You can retry with the same reference after correcting the customer details.

{
  "event": "virtual-account.rejected",
  "data": {
    "id": "64b2c1234567890",
    "reference": "ref_usd_123",
    "status": "rejected",
    "reason": "Customer verification failed",
    "currency": "USD",
    "createdAt": "2026-03-01T10:00:00.000Z",
    "updatedAt": "2026-03-01T10:00:03.000Z"
  }
}

NGN rejections have the NGN account shape with accountNumber, accountName and bankName set to null.

Testing webhooks on staging

On staging (https://sandbox-api.userivo.co), virtual accounts are simulated so you can test your webhook handling end to end:

NGN accounts (/virtual-accounts/ngn/temporary and /virtual-accounts/ngn/permanent) are created instantly with dummy account details, and virtual-account.created is sent straight away.
USD accounts (/virtual-accounts/usd) return pending and under review as in production. About 3 seconds later the account is approved with dummy bank details and virtual-account.created is sent.
Use a reference containing reject (for example ref_reject_001) to simulate a rejection. NGN requests then return 400 immediately; USD requests still return pending and under review. In both cases virtual-account.rejected is sent.

Sandbox account numbers cannot receive real money.

Security

Keep webhook secrets on your backend only. Verify the x-webhook-signature header before trusting a payload, and return a 2xx response only after your server accepts the event. To rotate a webhook secret today, delete the webhook URL and create it again. Store the new secret on your backend before enabling event handling for that URL.

Supported IP allowlist

Supported IPs are configured from the business dashboard and apply to signed Rivo Business API-key requests. If no supported IPs are configured, signed API-key requests are accepted from any IP address after normal authentication and signature checks pass. Once at least one supported IP is configured, Rivo only accepts signed API-key requests from the configured IP addresses.

Add supported IP

POST /business/v1/supported-ips
Authorization: Bearer BUSINESS_DASHBOARD_JWT
Content-Type: application/json

{
  "ipAddress": "203.0.113.10"
}

ipAddress must be a valid IPv4 or IPv6 address. Each business can configure up to 5 supported IP addresses. Example response:

{
  "status": "success",
  "message": "Supported IP added successfully",
  "data": {
    "_id": "6a51a0000000000000000002",
    "businessId": "69f13c6445e423d22696ad09",
    "ipAddress": "203.0.113.10",
    "createdAt": "2026-07-11T01:45:00.000Z",
    "updatedAt": "2026-07-11T01:45:00.000Z"
  }
}

List supported IPs

GET /business/v1/supported-ips
Authorization: Bearer BUSINESS_DASHBOARD_JWT

Example response:

{
  "status": "success",
  "message": "Supported IPs retrieved successfully",
  "data": [
    {
      "_id": "6a51a0000000000000000002",
      "businessId": "69f13c6445e423d22696ad09",
      "ipAddress": "203.0.113.10",
      "createdAt": "2026-07-11T01:45:00.000Z",
      "updatedAt": "2026-07-11T01:45:00.000Z"
    }
  ]
}

Delete supported IP

DELETE /business/v1/supported-ips/{id}
Authorization: Bearer BUSINESS_DASHBOARD_JWT

Example response:

{
  "status": "success",
  "message": "Supported IP deleted successfully",
  "data": {}
}

If a signed API-key request comes from an IP address outside the configured allowlist, Rivo returns:

{
  "status": "error",
  "message": "IP address is not allowed",
  "data": {}
}

Get Started

Core Concepts

Testing and Launch

Current rollout note

Manage webhook URLs

Create webhook

List webhooks

Delete webhook

Delivery format

Verify the signature

Events

payment.created

payment.completed

payment.failed

payment_link.created

payment_link.paid

payment_link.expired

transfer.created

transfer.completed

transfer.failed

virtual-account.created

virtual-account.rejected

Testing webhooks on staging

Security

Supported IP allowlist

Add supported IP

List supported IPs

Delete supported IP

​Current rollout note

​Manage webhook URLs

​Create webhook

​List webhooks

​Delete webhook

​Delivery format

​Verify the signature

​Events

​payment.created

​payment.completed

​payment.failed

​payment_link.created

​payment_link.paid

​payment_link.expired

​transfer.created

​transfer.completed

​transfer.failed

​virtual-account.created

​virtual-account.rejected

​Testing webhooks on staging

​Security

​Supported IP allowlist

​Add supported IP

​List supported IPs

​Delete supported IP

Current rollout note

Manage webhook URLs

Create webhook

List webhooks

Delete webhook

Delivery format

Verify the signature

Events

payment.created

payment.completed

payment.failed

payment_link.created

payment_link.paid

payment_link.expired

transfer.created

transfer.completed

transfer.failed

virtual-account.created

virtual-account.rejected

Testing webhooks on staging

Security

Supported IP allowlist

Add supported IP

List supported IPs

Delete supported IP