Webhooks

Receive real-time event notifications at your server without polling.

OZZOBiT Webhooks allow you to receive real-time notifications about order status changes, KYC events, and other important events at your server endpoint. Instead of continuously polling our API for status updates, we push data to you when events occur.

Supported Webhook Types

📦

Order Webhooks

Notifications for order lifecycle events including creation, payment processing, completion, and failure.

🆔

KYC Webhooks

Notifications when KYC verification status changes (pending, approved, rejected, retry needed).

Adding / Updating Your Webhook URL

Navigate to Partner Dashboard

Go to Settings then Webhooks

In the settings section, find the Webhooks configuration panel.

Add Your Endpoint URL

Enter your HTTPS webhook endpoint URL and save. You can add multiple URLs if needed.

⚠️

Webhook Requirements

Your endpoint must use HTTPS (TLS 1.2+)
Your server must respond with HTTP 200 status within 10 seconds
Webhook payloads are sent as POST requests with JSON body
We retry failed deliveries up to 3 times with exponential backoff

Order Webhooks

Event	Description	Status
ORDER_CREATED	A new order has been created	Info
ORDER_PROCESSING	Payment is being processed	Processing
ORDER_COMPLETED	Payment successful, crypto sent/completed	Success
ORDER_FAILED	Order failed due to payment or processing error	Failed
ORDER_CANCELLED	Order was cancelled by user or system	Cancelled
PENDING_DELIVERY_FROM_OZZOBiT	Crypto is being sent from OZZOBiT to user wallet	Pending
AWAITING_PAYMENT_FROM_USER	Waiting for user to complete payment	Awaiting
PAYMENT_DONE_MARKED_BY_USER	User marked payment as done, verifying	Verifying

Event	Description	Status
ORDER_CREATED	Sell order created, awaiting crypto deposit	Info
AWAITING_CRYPTO_DEPOSIT	Waiting for user to send crypto to deposit address	Awaiting
CRYPTO_DEPOSIT_RECEIVED	Crypto received from user, fiat processing started	Received
FIAT_PROCESSING	Converting crypto to fiat and initiating bank transfer	Processing
FIAT_SENT	Fiat transfer initiated to user bank account	Sent
ORDER_COMPLETED	Fiat successfully delivered to user bank account	Complete
ORDER_FAILED	Off-ramp order failed	Failed
ORDER_CANCELLED	Off-ramp order cancelled by user	Cancelled
ORDER_REFUNDED	Fiat refunded to user due to fulfillment failure	Refunded

Decrypting Webhook Payload

ℹ️

Encryption

All webhook payloads from OZZOBiT are signed as JWT tokens. You must verify and decode them using your Partner Access Token before processing on your backend.

See our decryption guide for detailed implementation examples in JavaScript, Java, and Go.

KYC Webhooks

Event	KYC Status	Description
KYC_SUBMITTED	SUBMITTED	Triggered when a user submits their KYC details
KYC_APPROVED	APPROVED	Triggered when the user's KYC verification is approved
KYC_REJECTED	REJECTED	Triggered when the user's KYC verification is rejected

Webhook Response Schema

Field	Type	Description
eventName	string	Name of the webhook event
orderId	string	Unique identifier for the order
partnerOrderId	string	Your reference ID for this order
status	string	Current status of the order
cryptoAmount	number	Amount of cryptocurrency
fiatAmount	number	Amount in fiat currency
fiatCurrency	string	Fiat currency code (USD, EUR, etc.)
cryptoCurrency	string	Cryptocurrency code (BTC, ETH, etc.)
fromWalletAddress	string	Sender wallet address (for off-ramp)
toWalletAddress	string	Recipient wallet address (for on-ramp)
timestamp	string	ISO 8601 timestamp of the event
webhookData	object	Additional event-specific data

Sample Webhook Payloads

order-completed.jsonjson

{
  "eventName": "ORDER_COMPLETED",
  "data": {
    "partnerOrderId": "your-order-123",
    "id": "OZZOBiT-order-abc",
    "status": "COMPLETED",
    "fiatCurrency": "USD",
    "fiatAmount": 100.00,
    "cryptoCurrency": "ETH",
    "cryptoAmount": 0.045,
    "fromWalletAddress": null,
    "toWalletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8bD21",
    "network": "ethereum",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8bD21",
    "createdAt": "2024-01-15T10:30:00Z",
    "completedAt": "2024-01-15T10:32:15Z"
  }
}

order-failed.jsonjson

{
  "eventName": "ORDER_FAILED",
  "data": {
    "partnerOrderId": "your-order-456",
    "id": "OZZOBiT-order-def",
    "status": "FAILED",
    "failureMessage": "Payment declined by issuing bank",
    "fiatCurrency": "USD",
    "fiatAmount": 50.00,
    "createdAt": "2024-01-15T11:00:00Z"
  }
}

kyc-approved.jsonjson

{
  "eventName": "KYC_APPROVED",
  "data": {
    "kycStatus": "APPROVED",
    "eventID": "KYC_APPROVED",
    "partnerUserId": "0870c29f-75a8-4091-a068-775fa4577172",
    "partnerCustomerId": "12345"
  }
}