Webhooks

Real-time notifications for order status changes. When an order transitions to a new status, the system sends a signed HTTP POST to your configured webhook URL.

Event model

A single event type is used for all order updates: order.status.changed.

Payload shape

{
  "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_id": "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"
  }
}

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:

expected = HMAC-SHA256(webhook_secret, "<timestamp>.<raw_body>")
valid    = constant_time_compare(expected, signature_from_header)

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

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
dispute_started	Dispute opened

Get webhook config

get

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/webhooks

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

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Responses

200

Webhook configuration retrieved

application/json

401

Unauthorized — invalid or missing API key

get

/api/v1/partner/webhooks

HTTPcURLJavaScriptPython

GET /api/v1/partner/webhooks HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "url": "https://partner.example.com/webhooks/unigox",
    "enabled": true
  }
}

Register webhook URL

post

https://api-staging.unigox.comhttps://api.unigox.com

/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

ApiKeyAuth

X-API-KeystringRequired

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

Body

application/json

urlstring · uriRequired

HTTPS URL that will receive webhook events

Example: https://partner.example.com/webhooks/unigox

Responses

200

Webhook registered successfully

application/json

400

Bad request — missing or invalid URL

application/json

401

Unauthorized — invalid or missing API key

post

/api/v1/partner/webhooks

HTTPcURLJavaScriptPython

POST /api/v1/partner/webhooks HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "url": "https://partner.example.com/webhooks/unigox"
}

{
  "success": true,
  "data": {
    "url": "https://partner.example.com/webhooks/unigox",
    "enabled": true
  }
}

Delete webhook

delete

https://api-staging.unigox.comhttps://api.unigox.com

/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

ApiKeyAuth

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

200

Webhook deleted successfully

application/json

401

Unauthorized — invalid or missing API key

delete

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

HTTPcURLJavaScriptPython

DELETE /api/v1/partner/webhooks/{id} HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "message": "webhook deleted"
  }
}

Test webhook

post

https://api-staging.unigox.comhttps://api.unigox.com

/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

ApiKeyAuth

X-API-KeystringRequired

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

Responses

200

Test event delivered successfully

application/json

400

Webhook URL not configured

application/json

401

Unauthorized — invalid or missing API key

502

Webhook delivery failed — target endpoint returned non-2xx or timed out

application/json

post

/api/v1/partner/webhooks/test

HTTPcURLJavaScriptPython

POST /api/v1/partner/webhooks/test HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "delivered": true,
    "http_status": 200
  }
}