🪝Webhooks

Closed Beta — Webhooks are currently in closed beta testing. To request access, reach out to @kiryl_sol on Telegram.

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 — alerts when multiple wallets buy the same token — Accumulation — 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.

{
  "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.

{
  "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.