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

# Webhooks

> Receive real-time event notifications from RebelFi

RebelFi sends webhook events to the endpoint URL configured in your dashboard **Settings**. Register your endpoint before going live.

## Payload Envelope

All webhook events share this common structure:

```json theme={null}
{
  "event": "customer.approved",
  "timestamp": "2026-03-15T12:00:00Z",
  "data": { ... }
}
```

| Field       | Type   | Description                                   |
| ----------- | ------ | --------------------------------------------- |
| `event`     | string | Event type identifier                         |
| `timestamp` | string | ISO 8601 timestamp of when the event occurred |
| `data`      | object | Event-specific payload                        |

## Events

### `customer.approved`

Fired when a recipient's KYB verification passes. The recipient is now eligible for on-ramp and off-ramp accounts.

```json theme={null}
{
  "event": "customer.approved",
  "timestamp": "2026-03-15T12:00:00Z",
  "data": {
    "customer_id": 1,
    "name": "OnEdge"
  }
}
```

<Info>
  Ramp accounts are not auto-created on approval. After receiving this event, use the API to create on-ramp and/or off-ramp accounts for the recipient.
</Info>

### `customer.declined`

Fired when a recipient's KYB verification fails.

```json theme={null}
{
  "event": "customer.declined",
  "timestamp": "2026-03-15T12:00:00Z",
  "data": {
    "customer_id": 1,
    "name": "OnEdge"
  }
}
```

### `transaction.completed`

Fired when an on-ramp USD deposit has been converted to USDC/USDT and delivered to the designated wallet.

```json theme={null}
{
  "event": "transaction.completed",
  "timestamp": "2026-03-20T14:35:00Z",
  "data": {
    "transaction_id": 1,
    "customer_id": 1,
    "type": "onramp",
    "usd_amount": "50000",
    "total_fee": "125",
    "delivered_amount": "49875"
  }
}
```

### `transaction.failed`

Fired when an on-ramp transaction encounters an error during conversion.

```json theme={null}
{
  "event": "transaction.failed",
  "timestamp": "2026-03-20T14:35:00Z",
  "data": {
    "transaction_id": 1,
    "customer_id": 1,
    "type": "onramp",
    "usd_amount": "50000",
    "error": "rejected"
  }
}
```

### `offramp_transaction.completed`

Fired when an off-ramp transaction has been converted and USD delivered to the bank account.

```json theme={null}
{
  "event": "offramp_transaction.completed",
  "timestamp": "2026-03-20T14:35:00Z",
  "data": {
    "transaction_id": 2,
    "customer_id": 1,
    "type": "offramp",
    "usd_amount": "25000",
    "total_fee": "62.50",
    "delivered_amount": "24937.50"
  }
}
```

### `offramp_transaction.failed`

Fired when an off-ramp transaction encounters an error.

```json theme={null}
{
  "event": "offramp_transaction.failed",
  "timestamp": "2026-03-20T14:35:00Z",
  "data": {
    "transaction_id": 2,
    "customer_id": 1,
    "type": "offramp",
    "usd_amount": "25000",
    "error": "rejected"
  }
}
```

## Best Practices

<Note>
  * **Respond with HTTP 200 immediately** — process the event asynchronously. RebelFi expects a quick acknowledgment.
  * **Check the `event` field** before acting on the payload. Your endpoint will receive all event types.
  * **Log raw payloads** for reconciliation and debugging.
  * **Handle duplicates** — in rare cases, the same event may be delivered more than once. Use the `data` fields to deduplicate.
</Note>