Webhooks

Webhooks allow you to listen to real-time events on your Obiex account. When an event occurs (e.g., a withdrawal is successful or pending), Obiex sends a POST request with a JSON payload to your server. It also includes a security header so you can verify the request came from Obiex.

Setting Up Webhooks

Log in to your Obiex dashboard
Navigate to Settings > Developers > Webhook Url
Add your webhook endpoint URL
Copy your Signature Secret

Event Payload and Structure

Obiex webhook events contain a JSON payload with the details of the event. We send webhooks for both withdrawal and deposit events. Below are examples of webhook payloads you might receive.

Withdrawals

When a withdrawal is initiated or completed, we send a webhook event.

{
  "type": "WITHDRAWAL",
  "currency": "USDT",
  "amount": 10,
  "status": "PENDING",
  "reference": "eba50518-58bf-430b-b603-d52f9794a8ee",
  "transactionId": "d1ef5d75-0883-4183-9367-3d0417781fff",
  "createdAt": "2026-03-26T09:10:50.611Z",
  "lastUpdated": "2026-03-26T09:10:50.611Z",
  "hash": null,
  "network": "BSC",
  "address": "0x1FFE2134c82D07227715af2A12D1406165A305BF"
}

{
  "type": "WITHDRAWAL",
  "currency": "USDT",
  "amount": 10,
  "status": "SUCCESSFUL",
  "reference": "6698fa68-9d39-40c5-87aa-c72b706437ae",
  "transactionId": "b1ce4f58-3141-4449-938f-8329511497ec",
  "createdAt": "2026-03-26T09:29:39.420Z",
  "lastUpdated": "2026-03-26T09:29:39.420Z",
  "hash": "adfb8a07-7193-4b19-8bcd-88e60d1c03d1",
  "network": "BSC",
  "address": "0x1FFE2134c82D07227715af2A12D1406165A305BF"
}

Deposits

We also send webhook event on deposit action.

{
  "hash": "0xe62236173d7427b73782c4d09863f01de418b7a2029841bcabfb35870c8d4f6c",
  "type": "DEPOSIT",
  "currency": "BNB",
  "address": "0x6f44D28c9aD050a101020a34B874Fd1B9Ed56Cdd",
  "amount": 0.3,
  "status": "CONFIRMED",
  "reference": "cbbf9e70-6e79-4513-905c-8dc584fbfee2",
  "transactionId": "8e91df33-077d-4702-9097-25051f21fb74",
  "createdAt": "2024-06-06T12:56:32.076Z",
  "lastUpdated": "2024-06-06T12:56:32.076Z"
}

Business Collections

If you use Business Collections to collect fiat payments from your customers, we send a COLLECTION webhook as each collection progresses.

{
  "type": "COLLECTION",
  "reference": "col_9f639b9f2a4a4b0e8e0e2d9c9d7a9d3e",
  "customerId": "9b1d6a3d-df3e-4e33-9f2b-1c2e3a9b6a11",
  "collectionType": "FIAT",
  "status": "COMPLETED",
  "sourceCurrency": "NGNX",
  "sourceAmount": 5000,
  "targetCurrency": "USDT",
  "targetAmount": 3.31,
  "senderInfo": {
    "senderName": "Ada Okafor",
    "senderAccount": "0123456789",
    "bank": "GTBank"
  },
  "accountNumber": "9012345678",
  "accountName": "Obiex-Ada Okafor",
  "bankName": "Wema Bank",
  "walletAddress": null,
  "network": null,
  "accountExpiresAt": "2026-08-17T10:47:00.000Z",
  "createdAt": "2026-08-17T10:17:00.000Z",
  "lastUpdated": "2026-08-17T10:19:32.000Z"
}

{
  "type": "COLLECTION",
  "reference": "col_2b7a4c8e9f1d4a6b8c0d2e4f6a8b0c2d",
  "customerId": "9b1d6a3d-df3e-4e33-9f2b-1c2e3a9b6a11",
  "collectionType": "FIAT",
  "status": "HELD",
  "sourceCurrency": "NGNX",
  "sourceAmount": 5000,
  "targetCurrency": null,
  "targetAmount": null,
  "senderInfo": {
    "senderName": "Chuka Eze",
    "senderAccount": "0198765432",
    "bank": "Access Bank"
  },
  "accountNumber": "9012345678",
  "accountName": "Obiex-Ada Okafor",
  "bankName": "Wema Bank",
  "walletAddress": null,
  "network": null,
  "accountExpiresAt": "2026-08-17T10:47:00.000Z",
  "createdAt": "2026-08-17T10:17:00.000Z",
  "lastUpdated": "2026-08-17T10:18:05.000Z"
}

A HELD status means the payer’s name didn’t match the customer registered on the collection. The funds are safe, but require manual review before you treat the collection as paid.

Signature Verification

All webhook requests include the header:

x-obiex-signature: <HMAC-SHA512 hex digest>

This signature is generated using your Signature Secret as a HMAC SHA512 of the raw request body.

Verifying the Signature

Read the raw request body as a string (do not parse first).
Read the x-obiex-signature header.
Compute HMAC SHA512 of the raw body using your Signature Secret.
Hex-encode the result.
Compare with the received signature.

Example: Node.js (Express)

import crypto from 'crypto';
import express from 'express';

const app = express();
const signatureSecret = process.env.OBIEX_SIGNATURE_SECRET!;

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const receivedSignature = req.headers['x-obiex-signature'] as string;
  const body = req.body.toString();
  
  const computedSignature = crypto
    .createHmac('sha512', signatureSecret)
    .update(body)
    .digest('hex');
  
  if (computedSignature !== receivedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  // Signature is valid - process webhook
  const webhookEvent = JSON.parse(body);
  console.log('Received webhook:', webhookEvent);
  
  res.status(200).send('Received');
});

app.listen(3000, () => {
  console.log('Listening for webhooks on port 3000');
});

Always verify the signature before processing any webhook event to ensure it was sent by Obiex.

Getting Started

Wallet Addresses

Currencies

Business Collections

Trades

Payouts

Transactions

Invoice Settlement

Setting Up Webhooks

Event Payload and Structure

Withdrawals

Deposits

Business Collections

Signature Verification

Verifying the Signature

Example: Node.js (Express)

​Setting Up Webhooks

​Event Payload and Structure

​Withdrawals

​Deposits

​Business Collections

​Signature Verification

​Verifying the Signature

​Example: Node.js (Express)

Setting Up Webhooks

Event Payload and Structure

Withdrawals

Deposits

Business Collections

Signature Verification

Verifying the Signature

Example: Node.js (Express)