# 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/multi-wallet.md)— alerts when multiple wallets buy the same token \
— [**Accumulation**](/start/interface-and-buttons-in-telegram/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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.raybot.app/start/dev/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.