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

# Webhook notifications

> Deposit and withdrawal event schemas, statuses and delivery behavior.

THE NOTIFICATION

# Deposit and withdrawal notifications

Bullring sends outbound notifications through the webhook endpoint configured in the dashboard. Endpoint management is dashboard-only; partners use this page to implement the receiver.

## Delivery headers

Every delivery includes:

```http theme={null}
X-BULLRING-SIGNATURE: t=<timestamp>,v1=<hash>
```

The `v1` value is a Base64 HMAC-SHA256 signature created with the endpoint
secret. See [Webhook verification](https://docs.bullring.finance/11-webhook-verification.md) for the exact
verification procedure.

## Event envelope

Webhook bodies use this envelope:

```json theme={null}
{
  "event": "deposit.status.paid",
  "data": {},
  "id": "event-uuid",
  "timestamp": "2026-11-22T00:31:47.602Z"
}
```

Treat `X-Bullring-Webhook-Id` as the delivery identity for deduplication. Do not use the payload timestamp as a deduplication key.

## Deposit events

### `deposit.status.paid`

```json theme={null}
{
  "event": "deposit.status.paid",
  "data": {
    "id": "collection-uuid",
    "reference": "SIM179530723115565090046",
    "account_id": "store-uuid",
    "net_amount": {
      "value": "100.00",
      "currency": "NGN"
    },
    "gross_amount": {
      "value": "100.00",
      "currency": "NGN"
    },
    "fee": {
      "value": "0.00",
      "currency": "NGN"
    },
    "status": "paid",
    "created_at": "2026-11-22T00:27:14.270Z",
    "updated_at": "2026-11-22T00:31:47.602Z",
    "payer": {},
    "receiver": {},
    "settlement": {
      "settlement_at": "2026-11-22T00:31:47.602Z",
      "transaction_hash": null
    }
  }
}
```

### `deposit.status.unpaid`

The same deposit data shape is sent with:

```json theme={null}
{
  "event": "deposit.status.unpaid",
  "data": {
    "status": "unpaid"
  }
}
```

## Withdrawal events

Withdrawal status event names are:

| Event | Meaning |
| - | - |
| `withdrawal.status.not_initiated` | Withdrawal has not started |
| `withdrawal.status.in_progress` | Withdrawal is being processed |
| `withdrawal.status.completed` | Provider settlement completed |
| `withdrawal.status.failed` | Provider or validation failure |
| `withdrawal.status.reversed` | A previously processed withdrawal was reversed |

Example:

```json theme={null}
{
  "event": "withdrawal.status.completed",
  "data": {
    "id": "withdrawal-uuid",
    "amount": "1000",
    "currency": "NGN",
    "status": "completed",
    "payment_rail": "BANK_TRANSFER",
    "externalAccountId": "recipient-uuid",
    "description": "Partner settlement",
    "createdAt": "2026-11-22T00:31:47.602Z"
  }
}
```

## Delivery and retry rules

* Convoy performs delivery and retries.
* Return a `2xx` only after the event is durably accepted.
* Return a non-`2xx` response when the event was not accepted.
* Deduplicate by webhook event ID.
* Do not assume delivery order.
* A retry may contain a new delivery attempt while representing the same business event.
* Do not perform irreversible business work before signature verification and deduplication.

## Status handling

Use the event name as the source of truth for the transition. Store the raw event, received timestamp and verification key ID for audit and replay diagnostics.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.