> For the complete documentation index, see [llms.txt](https://docs.raybot.app/start/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raybot.app/start/dev/webhooks.md).

# Webhooks

### Overview

Webhooks let you receive real-time wallet activity notifications as structured JSON delivered via HTTP POST to your own endpoint. Instead of reading notifications in Telegram or Discord, your server gets a programmatic payload for every transaction — ideal for building bots, dashboards, alerting systems, or automated trading strategies.

All chains supported by RayBot work with webhooks: **Solana, EVM (Ethereum, BSC, Base, Arbitrum, etc.), TRON, and Hypercore**.

### Getting Started

#### 1. Open the webhook menu

Send `/webhook` in the RayBot Telegram bot.

#### 2. Add a webhook

Tap **Add Webhook** and follow the prompts:

1. **URL** — Your endpoint must be a public `https://` URL. Private/internal addresses (`localhost`, `192.168.*`, etc.) are rejected.
2. **Label** (optional) — A friendly name for the webhook (max 50 characters).
3. **Authorization header** (optional) — A value sent as the `Authorization` header on every request (e.g. `Bearer mytoken123`). Max 200 characters.

RayBot sends a test `POST` to your URL before saving. Your endpoint must return a `2xx` status code within 1 second.

#### 3. Add wallet addresses

Once the webhook is created, tap **Manage Addresses** to add the wallet addresses you want to monitor. Wallets added to a webhook work the same as wallets on your main account — all filters and notification settings apply.

#### **4. Configure filters and features**

A webhook supports the full set of RayBot tools — all the same filters and features available in a regular bot apply here too:

— All transaction filters (by type, amount, token, age, etc.)\
— [**Multi Wallet** ](/start/interface-and-buttons-in-telegram/signals/multi-wallet.md)— alerts when multiple wallets buy the same token\
— [**Accumulation**](/start/interface-and-buttons-in-telegram/signals/accumulation.md) — signals when a single wallet builds up a position

This way you receive pre-filtered notifications, ready to fit your exact use case.

📌 **To access your Webhook settings:**

* **From Telegram:** /start → 👾 **Groups** → select your Webhook from the list
* **From the Web interface:** navigate to the **Destinations** section and select your Webhook from the list.

### Managing Webhooks

From the `/webhook` menu you can:

| Action               | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| **Pause / Resume**   | Temporarily stop or restart delivery without deleting the webhook |
| **Manage Addresses** | Add or remove tracked wallets                                     |
| **Change Auth**      | Update or remove the Authorization header (send `none` to remove) |
| **Delete**           | Permanently remove the webhook and all its tracked wallets        |

### Limits

| Plan         | Max Webhooks |
| ------------ | ------------ |
| Free         | 0            |
| Hobby 50/100 | 1            |
| Pro 200      | 3            |
| Whale 500+   | 5            |

Each webhook has its own independent set of tracked wallets. Wallet limits follow your subscription plan.

### Delivery

#### Request format

Every notification is an HTTP `POST` with a JSON body. The request includes these headers:

| Header                 | Description                                             |
| ---------------------- | ------------------------------------------------------- |
| `Content-Type`         | `application/json`                                      |
| `User-Agent`           | `RayBot-Webhook/1.0`                                    |
| `X-RayBot-Event`       | The event type (e.g. `buy`, `sell`, `transfer_in`)      |
| `X-RayBot-Delivery-Id` | Unique ID for this delivery (the transaction signature) |
| `Authorization`        | Your configured auth header value (if set)              |

#### Timeouts and retries

* Your server must respond **within 1 second**.
* If delivery fails with a `5xx` status or a network error (timeout, connection refused), the request is retried automatically.
* `4xx` errors are **not** retried — these indicate a problem on your end (bad auth, endpoint not found, etc.).

#### Auto-disable on repeated failures

After **10 consecutive failed deliveries**, the webhook is automatically paused and all its wallets are set to inactive. You will see the failure count in the webhook management screen. Resume the webhook from the `/webhook` menu once the issue is fixed — the failure counter resets on the next successful delivery.

### Payload Reference

#### Standard Events

Event types: `buy`, `sell`, `swap`, `transfer_in`, `transfer_out`, `nft_transfer`, `token_mint`, `add_liquidity`, `remove_liquidity`, `migrate`, `other`.

```json
{
  "id": "4vMfGj8qR7Kx9nTpL2wYcAe5dHs6bN1mZuQoFrJiDk3X8yVtW0aCgEhB7UlPnSRf",
  "event_type": "buy",
  "timestamp": "2025-06-10T14:22:03.417Z",
  "chain": "solana",
  "failed": false,
  "source": "raydium",
  "fee_payer": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "followed_wallets": [
    {
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "wallet_name": "Smart Money #3",
      "funded_at": "2024-11-05T09:18:30.000Z",
      "sol_balance": 24.83
    }
  ],
  "token_changes": [
    {
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "direction": "in",
      "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
      "amount_raw": "5897420000",
      "amount": 5897.42,
      "price_usd": 0.00002847,
      "value_usd": 167.94
    },
    {
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "direction": "out",
      "mint": "So11111111111111111111111111111111111111112",
      "amount_raw": "1120000000",
      "amount": 1.12,
      "price_usd": 149.95,
      "value_usd": 167.94
    }
  ],
  "tokens": {
    "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263": {
      "symbol": "BONK",
      "name": "Bonk",
      "decimals": 6,
      "price_usd": 0.00002847,
      "supply": 93526183000000,
      "created": "2022-12-25T00:00:00.000Z",
      "image": null,
      "socials": {
        "twitter": null,
        "telegram": null,
        "website": null
      }
    },
    "So11111111111111111111111111111111111111112": {
      "symbol": "SOL",
      "name": "Wrapped SOL",
      "decimals": 9,
      "price_usd": 149.95,
      "supply": 0,
      "created": null,
      "image": null,
      "socials": {
        "twitter": null,
        "telegram": null,
        "website": null
      }
    }
  },
  "position": {
    "side": "buy",
    "is_new_position": false,
    "is_closed": false,
    "total_quantity": 18420.6,
    "average_cost_basis": 0.00002513,
    "current_price": 0.00002847,
    "total_invested": 462.87,
    "realized_pnl": 0,
    "unrealized_pnl": 61.56
  },
  "fees": {
    "priority_fee": 0.000005,
    "jito_tip": 0.001,
    "total_tip": 0.001005
  },
  "event": {
    "type": "buy",
    "account": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "mintIn": "So11111111111111111111111111111111111111112",
    "mintOut": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "amountIn": 1120000000,
    "amountOut": 5897420000,
    "valueIn": 1.12,
    "valueOut": 5897.42
  }
}
```

**Field notes**

| Field           | Notes                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | Transaction signature. Also used as the delivery ID.                                                                                                        |
| `failed`        | `true` if the on-chain transaction failed.                                                                                                                  |
| `source`        | DEX or protocol that processed the trade (e.g. `raydium`, `jupiter`, `orca`, `uniswap`).                                                                    |
| `token_changes` | One entry per token flow per wallet. `direction` is `in` or `out`. `amount_raw` is the raw integer value before decimals.                                   |
| `tokens`        | Metadata map keyed by mint address. Includes price, supply, socials, and image.                                                                             |
| `position`      | Present when RayBot has position tracking data for the token. `is_new_position` means this is the first buy. `is_closed` means the position was fully sold. |
| `fees`          | Solana-specific priority fees and Jito tips. `null` on other chains.                                                                                        |
| `event`         | Raw event details from the parser (swap mints, transfer sender/receiver, etc.).                                                                             |

#### Multi-Buy and Accumulation Events

Webhooks also deliver `multi_buy` events (multiple tracked wallets buying the same token within a short window) and `accumulation` events (a single wallet repeatedly buying the same token past your threshold). These use the same top-level structure with additional `multi_buy` or `accumulation` objects containing purchase details.

#### Test Event

Sent once when you first add a webhook to verify your endpoint.

```json
{
  "event_type": "test",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "message": "RayBot webhook verification"
}
```

### Security Recommendations

* **Use the Authorization header.** Set a secret token when creating your webhook and validate it on every incoming request.
* **Verify the User-Agent.** All RayBot webhook requests use `RayBot-Webhook/1.0`.
* **Use HTTPS only.** RayBot rejects non-HTTPS URLs.
* **Respond quickly.** Return a `2xx` within 1 second. Do heavy processing asynchronously after acknowledging the request.