search
Ctrlk
Postman Collection

bellWebhooks

Real-time notifications for order and KYC status changes. The system sends a signed HTTP POST to your configured webhook URL on every relevant event.

Event model

Two event types are delivered:

Event type
Fired when

order.status.changed

An order transitions to a new status

user.kyc.updated

A user's KYC verification is approved or declined

All events share the same envelope (event_id, event_type, created_at, data) and the same signature scheme. The structure of the data object differs per event type.

Payload shape — order.status.changed

{
  "event_id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "order.status.changed",
  "created_at": "2026-02-01T12:00:05Z",
  "data": {
    "order_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "status": "crypto_received",
    "user_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "crypto_amount": "101.500000",
    "crypto_currency": "USDT",
    "fiat_amount": "152880.00",
    "fiat_currency": "NGN",
    "provider": "p2p",
    "payment_details_id": "987"
  }
}

Payload shape — user.kyc.updated

Fired when a user's KYC status transitions to verified or rejected. Use this event to unlock order creation for the user on your side.

When KYC is declined, rejection_reasons is included:

kyc_status values: VERIFIED | REJECTED

Signature verification

Every delivery includes two headers for HMAC-SHA256 verification:

  • X-Unigox-Signature: sha256=<hex> — HMAC of "<timestamp>.<raw_body>"

  • X-Unigox-Timestamp: <unix_seconds>

Verification pseudocode:

Delivery guarantees

  • At-least-once delivery. Your endpoint may receive the same event more than once.

  • De-duplicate by event_id.

  • Respond with any 2xx status within 10 seconds to acknowledge receipt.

Retry policy

Failed deliveries (non-2xx or timeout) are retried with exponential backoff: 1 min → 5 min → 15 min → 1 h → 6 h → 12 h → 24 h (max 10 attempts over ~3.5 days).

Partner-facing statuses (order.status.changed)

Status
Description

created

Order created

awaiting_liquidity_provider

Waiting for vendor match

awaiting_crypto_transfer_authorization

Partner must authorize crypto transfer

crypto_received

Crypto received in escrow

fiat_payment_started

Buyer submitted fiat payment proof

fiat_payment_review_started

Payment proof under admin review

awaiting_fiat_received_confirmation

Proof approved, awaiting seller confirmation

completed

Order completed, crypto released

cancelled

Order cancelled or payment declined

failed

Escrow error, or fiat-anchored safety bound exceeded (see below)

dispute_started

Dispute opened

Fiat-anchored safety bound failure

For fiat-anchored off-ramp orders (anchor_type: "fiat"), if Switch quotes a crypto cost exceeding 1.20× the expected amount at the time of settlement, the order moves to failed status asynchronously (not during /initiate). The deposit is automatically refunded from escrow back to the partner wallet. Create a new quote to retry the trade flow.

hashtag
Get webhook config

get
/api/v1/partner/webhooks

Returns the current webhook configuration for your partner account, including the URL and whether the webhook is enabled.

Authorizations
X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Responses
chevron-right
200

Webhook configuration retrieved

application/json
successbooleanRequired

Indicates if the request was successful

Example: true
get
/api/v1/partner/webhooks

hashtag
Register webhook URL

post
/api/v1/partner/webhooks

Register or update the webhook URL for your partner account. The URL must use HTTPS. Once registered, the webhook is automatically enabled and will start receiving order status events.

Authorizations
X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Body
urlstring · uriRequired

HTTPS URL that will receive webhook events

Example: https://partner.example.com/webhooks/unigox
Responses
chevron-right
200

Webhook registered successfully

application/json
successbooleanRequired

Indicates if the request was successful

Example: true
post
/api/v1/partner/webhooks

hashtag
Delete webhook

delete
/api/v1/partner/webhooks/{id}

Remove the webhook URL and disable webhook delivery for your partner account. No further events will be sent until a new URL is registered.

Authorizations
X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Path parameters
idstringRequired

Webhook ID (any value accepted — the system uses the authenticated partner context)

Example: 1
Responses
chevron-right
200

Webhook deleted successfully

application/json
successbooleanRequired

Indicates if the request was successful

Example: true
delete
/api/v1/partner/webhooks/{id}

hashtag
Test webhook

post
/api/v1/partner/webhooks/test

Send a signed test event to your configured webhook URL. Uses the same HMAC-SHA256 signature scheme as production events. Use this to verify your endpoint is reachable and correctly validating signatures.

Authorizations
X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Responses
chevron-right
200

Test event delivered successfully

application/json
successbooleanRequired

Indicates if the request was successful

Example: true
post
/api/v1/partner/webhooks/test
PreviousOrdersNextModels

Last updated