> ## Documentation Index
> Fetch the complete documentation index at: https://developer.obiex.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Listen to real-time events and verify webhook requests from Obiex

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

1. Log in to your [Obiex dashboard](https://staging.app.obiex.finance/auth/login)
2. Navigate to **Settings** > **Developers** > **Webhook Url**
3. Add your webhook endpoint URL
4. 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.

<CodeGroup>
  ```json Pending Withdrawal theme={null}
  {
    "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"
  }
  ```

  ```json Successful Withdrawal theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

### Deposits

We also send webhook event on deposit action.

<CodeGroup>
  ```json Confirmed Deposit theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

<br />

## 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

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

### Example: Node.js (Express)

```typescript theme={null}
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');
});
```

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