Remitflex Documentation

RemitFlex can POST signed JSON events to your HTTPS endpoints whenever a swap, payment route, collection, local fiat order, or cNGN object is created or changes status. Manage endpoints in the merchant app under Webhooks, or via the API with JWT or an API key that includes api:read / api:write.

Quick setup

Create an endpoint

POST /v1/webhooks with an HTTPS url. Optionally set events to an allowlist; omit or pass null to receive all event types.

Store the signing secret

The create (and rotate) response includes secret (whsec_…) once. Use it to verify X-Remitflex-Signature.

Verify and acknowledge

Validate the signature, then return 2xx within ~10 seconds. RemitFlex retries failed deliveries with exponential backoff (up to 8 attempts).

Delivery headers

Header	Meaning
`Content-Type`	`application/json`
`X-Remitflex-Event`	Event type (e.g. `swap.updated`)
`X-Remitflex-Delivery`	Delivery id
`X-Remitflex-Timestamp`	Unix timestamp (seconds)
`X-Remitflex-Signature`	`t={ts},v1={hmac_hex}`

Signature verification

signed_payload = `${timestamp}.${rawBody}`
expected = HMAC_SHA256(signing_secret, signed_payload)  // hex

Compare v1 from the header to expected (constant-time). Reject if the timestamp is too far from your clock (e.g. ±5 minutes) to limit replay.

Payload shape

{
  "id": "event-uuid",
  "type": "swap.updated",
  "created": "2026-07-23T00:00:00.000Z",
  "data": {
    "id": "resource-uuid",
    "status": "completed",
    "previousStatus": "swapping"
  }
}

data is a resource snapshot. Status transitions include previousStatus and status (previousStatus is null on create).

Event catalog

Family	Types
Swaps	`swap.created`, `swap.updated`
Payment routes	`payment_route.created`, `payment_route.updated`, `payment_route.deposit.updated`
Collections	`collection.created`, `collection.updated`
Local fiat	`offramp.created`, `offramp.updated`, `onramp.created`, `onramp.updated`
cNGN	`cngn.convert.`, `cngn.withdrawal.`, `cngn.payout.`, `cngn.payin.`, `cngn.deposit.*` (`.created` / `.updated`); `cngn.customer.enabled`, `cngn.customer.failed`
Test	`webhook.test` (from `POST /v1/webhooks/{webhookEndpointId}/test` — delivered to that endpoint even if it is not on the allowlist)

Every subsequent status change emits *.updated (including cancel/expire), not only terminal states. cngn.customer.enabled fires once when KYC finishes and names match; cngn.customer.failed fires once on KYC failure or customer_name_bvn_mismatch.

API

{webhookEndpointId} is the RemitFlex webhook endpoint UUID from POST or GET /webhooks.

Method	Path	Scope
`POST`	`/v1/webhooks`	`api:write`
`GET`	`/v1/webhooks`	`api:read`
`GET`	`/v1/webhooks/{webhookEndpointId}`	`api:read`
`PATCH`	`/v1/webhooks/{webhookEndpointId}`	`api:write`
`POST`	`/v1/webhooks/{webhookEndpointId}/rotate-secret`	`api:write`
`DELETE`	`/v1/webhooks/{webhookEndpointId}`	`api:write` (soft revoke)
`GET`	`/v1/webhooks/{webhookEndpointId}/deliveries`	`api:read`
`POST`	`/v1/webhooks/{webhookEndpointId}/test`	`api:write`
`GET`	`/v1/webhooks/event-types`	`api:read`

Dashboard JWT sessions can call these routes without scopes. API keys need the matching api:read / api:write scope.

Security notes

URL must be HTTPS. Private, loopback, and link-local targets are rejected (SSRF protection).
Signing secrets are stored server-side so RemitFlex can sign outbound deliveries; the raw value is only shown on create/rotate.

Get started

Concepts

Collect

Convert & FX

Local money

Customers & ledger

Integration

Webhooks

Quick setup

Delivery headers

Signature verification

Payload shape

Event catalog

API

Security notes

​Quick setup

​Delivery headers

​Signature verification

​Payload shape

​Event catalog

​API

​Security notes

Quick setup

Delivery headers

Signature verification

Payload shape

Event catalog

API

Security notes