📩Webhooks API

Manage webhook notification destinations via the public API.

A webhook is a destination that receives HTTPS POST requests whenever a followed wallet produces a notification — the same events the Telegram bots deliver to chats.

Attaching wallets to a webhook is a separate step. This API only manages the webhook destination itself (URL, label, auth header, pause/resume). To add or remove the addresses that feed into a webhook, reuse the existing /publicapi/wallets/add, /publicapi/wallets/delete, and /publicapi/wallets/show endpoints, passing the webhook's id (returned by this API) as their user_id parameter and bot: 0.

🌐 Base URL

All requests are made to:

https://webapi.raybot.app

🔐 Authentication

Same as the rest of /publicapi — obtain an API key with /api in the RayBot Telegram Bot and pass it on every request.

Required Query Parameters:
api_user (string, required): Your API user ID
token (string, required): API authentication token

GET /publicapi/webhooks?api_user=your_user_id&token=your_api_key

Rate Limits

Public API endpoints (/publicapi): — 5 requests per 10 seconds

Plan gating

Webhooks are a paid feature. Your plan determines how many active webhooks you can have at once (paused and expired webhooks do not count toward the cap). On a free plan the cap is 0 — POST /publicapi/webhooks returns 403 WEBHOOK_NOT_AVAILABLE.

📋 Endpoints

List Webhooks

Endpoint: GET /publicapi/webhooks

Return every webhook owned by the caller (excluding soft-deleted ones), along with the plan's webhook limit and the number currently in use.

Parameters:

Query Parameters:
api_user (string, required): Your API user ID
token (string, required): API authentication token

Response:

{
  "webhooks": [
    {
      "id": "17408000000012345",
      "url": "https://example.com/hook",
      "label": "prod-alerts",
      "auth_header_set": true,
      "active": true,
      "status": "send",
      "consecutive_failures": 0,
      "address_count": 12,
      "created_at": "2026-04-17T10:15:00.000Z"
    }
  ],
  "limit": 5,
  "used": 1
}

id — use this as user_id when calling /publicapi/wallets/* to attach addresses.
auth_header_set — whether an Authorization header is configured. The value itself is never returned.
status — one of send, pause, expired. Only send counts toward used.

Status Codes:
200: Success
400: Invalid authentication parameters
401: Invalid authentication
429: Rate limit exceeded

Create Webhook

Endpoint: POST /publicapi/webhooks

Register a new webhook destination. The server sends a verification POST to the URL during creation and refuses to persist the webhook if that call does not return a 2xx response.

Parameters:

Query Parameters:
api_user (string, required): Your API user ID
token (string, required): API authentication token

Request Body:

{
  "url": "https://example.com/hook",
  "label": "prod-alerts",
  "auth_header": "Bearer my-secret"
}

Validation Rules:
url required, ≤500 characters, must be https://. Hostnames localhost, .local, .internal, and private / loopback / link-local / ULA IPs (both IPv4 and IPv6) are rejected.
label optional, ≤50 characters.
auth_header optional, ≤200 characters. Sent verbatim as the Authorization header on deliveries.

Verification Payload

While creating the webhook, the server POSTs this to your URL (5-second timeout, no redirects):

{
  "event_type": "test",
  "timestamp": "2026-04-17T10:15:00.000Z",
  "message": "RayBot webhook verification"
}

Headers: Content-Type: application/json, User-Agent: RayBot-Webhook/1.0, X-RayBot-Event: test, plus Authorization: <auth_header> if you set one. Reply with any 2xx status to accept.

Response:

{
  "id": "17408000000012345",
  "url": "https://example.com/hook",
  "label": "prod-alerts",
  "auth_header_set": true,
  "active": true,
  "status": "send",
  "consecutive_failures": 0,
  "address_count": 0,
  "created_at": "2026-04-17T10:15:00.000Z"
}

Status Codes:
201: Webhook created
400: Validation error (INVALID_URL, INVALID_LABEL, INVALID_AUTH_HEADER)
401: Invalid authentication
403: Plan limits — WEBHOOK_NOT_AVAILABLE (plan has 0 webhooks) or WEBHOOK_LIMIT_REACHED (already at cap)
422: TEST_FAILED — the verification POST did not succeed; the response body includes upstream_status and error
429: Rate limit exceeded

Get Webhook

Endpoint: GET /publicapi/webhooks/{id}

Return a single webhook by id.

Parameters:

Query Parameters:
api_user (string, required): Your API user ID
token (string, required): API authentication token
Path Parameters:
id (string, required): Webhook id returned from create/list.

Response: Same object shape as an item in the list response.

Status Codes:
200: Success
401: Invalid authentication
404: WEBHOOK_NOT_FOUND
429: Rate limit exceeded

Update Webhook

Endpoint: PATCH /publicapi/webhooks/{id}

Update the mutable fields on a webhook. The URL itself is immutable — to change it, delete and recreate the webhook.

Parameters:

Query Parameters:
api_user (string, required): Your API user ID
token (string, required): API authentication token
Path Parameters:
id (string, required): Webhook id

Request Body (any subset):

{
  "label": "new-label",
  "auth_header": "Bearer rotated",
  "active": false
}

Validation / Semantics:
label — same rules as create. null or "" clears it.
auth_header — same rules as create. null or "" removes the stored header.
active — toggle delivery:
false → pauses the webhook (status: "pause") and sets every active address on the webhook to pause.
true → resumes delivery (status: "send"), resets consecutive_failures to 0, and restores paused addresses to active.
Passing a url field returns 400 INVALID_URL.

Response: Full webhook object after the update (same shape as create).

Status Codes:
200: Updated
400: INVALID_URL (URL change attempted), INVALID_LABEL, INVALID_AUTH_HEADER
401: Invalid authentication
404: WEBHOOK_NOT_FOUND
429: Rate limit exceeded

Delete Webhook

Endpoint: DELETE /publicapi/webhooks/{id}

Delete the webhook. All addresses attached to it are also deleted. Allowed regardless of plan (free users can clean up after downgrade).

Parameters:

Query Parameters:
api_user (string, required): Your API user ID
token (string, required): API authentication token
Path Parameters:
id (string, required): Webhook id

Response: Empty body.

Status Codes:
204: Deleted
401: Invalid authentication
404: WEBHOOK_NOT_FOUND
429: Rate limit exceeded

Send Test Delivery

Endpoint: POST /publicapi/webhooks/{id}/test

Send the same verification payload as on creation, using the webhook's current URL and auth header. Useful for confirming a rotated auth_header or diagnosing delivery failures. Does not touch consecutive_failures and does not auto-disable the webhook.

Parameters:

Query Parameters:
api_user (string, required): Your API user ID
token (string, required): API authentication token
Path Parameters:
id (string, required): Webhook id

Response (success):

{
  "status_code": 200,
  "latency_ms": 142
}

Status Codes:
200: Upstream returned 2xx
401: Invalid authentication
404: WEBHOOK_NOT_FOUND
422: TEST_FAILED — body includes upstream_status, error, latency_ms
429: Rate limit exceeded

🔗 Managing Addresses

Use the existing /publicapi/wallets/* endpoints, setting:

user_id = the webhook's id (from list / create / get)
bot = 0

POST /publicapi/wallets/add?api_user=...&token=...
{
  "user_id": "17408000000012345",
  "bot": 0,
  "wallets": [
    { "wallet_address": "0xabc...", "wallet_name": "main" }
  ]
}

Addresses attached to a webhook respect the wallet limits that applied when the webhook was created. Use /publicapi/wallets/settings the same way to adjust per-address tx filters.

🚨 Error Codes

Errors returned by this API use a structured envelope:

{
  "error": {
    "code": "WEBHOOK_LIMIT_REACHED",
    "message": "Webhook limit reached",
    "details": { "limit": 5, "used": 5 }
  }
}

Code

HTTP

When

UNAUTHORIZED

400 / 401

Missing or invalid api_user/token

INVALID_URL

400

URL is malformed, not https, too long, or points at a private/internal host

INVALID_LABEL

400

label exceeds 50 characters

INVALID_AUTH_HEADER

400

auth_header exceeds 200 characters

WEBHOOK_NOT_FOUND

404

No webhook with that id owned by the caller

WEBHOOK_NOT_AVAILABLE

403

Plan limit is 0

WEBHOOK_LIMIT_REACHED

403

Plan limit reached — body includes limit, used

TEST_FAILED

422

Verification POST returned non-2xx or errored — body includes upstream_status, error

RATE_LIMIT_EXCEEDED

429

/publicapi rate limit hit

📦 Delivery Payload

Real notifications (not test pings) arrive as HTTPS POSTs with these headers:

Content-Type: application/json
User-Agent: RayBot-Webhook/1.0
X-RayBot-Event: <event_type>
X-RayBot-Delivery-Id: <uuid>
Authorization: <your auth_header>    # if configured

The body carries the same event schema the Telegram bots render — swaps, transfers, token mints, etc. After 10 consecutive failed deliveries the webhook auto-disables (active: false, status: "pause"); use PATCH … { "active": true } to re-enable once you've fixed the receiver.

🔧 SDKs and Examples

JavaScript/Node.js Example

const axios = require('axios');

const apiClient = axios.create({
  baseURL: 'https://webapi.raybot.app',
  timeout: 30000,
});

async function createWebhook(apiUser, token, { url, label, authHeader }) {
  const res = await apiClient.post(
    `/publicapi/webhooks?api_user=${apiUser}&token=${token}`,
    { url, label, auth_header: authHeader }
  );
  return res.data;
}

async function attachAddresses(apiUser, token, webhookId, wallets) {
  const res = await apiClient.post(
    `/publicapi/wallets/add?api_user=${apiUser}&token=${token}`,
    { user_id: webhookId, bot: 0, wallets }
  );
  return res.data;
}

(async () => {
  const webhook = await createWebhook('api_user_id', 'your_api_token', {
    url: 'https://example.com/hook',
    label: 'prod-alerts',
    authHeader: 'Bearer my-secret',
  });

  await attachAddresses('api_user_id', 'your_api_token', webhook.id, [
    { wallet_address: '0xabc...', wallet_name: 'main' },
  ]);

  console.log('Webhook ready:', webhook.id);
})();

Python Example

import requests

class RayBotWebhooks:
    def __init__(self, base_url, api_user, token):
        self.base_url = base_url
        self.params = {"api_user": api_user, "token": token}

    def create(self, url, label=None, auth_header=None):
        body = {"url": url, "label": label, "auth_header": auth_header}
        r = requests.post(f"{self.base_url}/publicapi/webhooks", params=self.params, json=body)
        r.raise_for_status()
        return r.json()

    def attach_addresses(self, webhook_id, wallets):
        body = {"user_id": webhook_id, "bot": 0, "wallets": wallets}
        r = requests.post(f"{self.base_url}/publicapi/wallets/add", params=self.params, json=body)
        r.raise_for_status()
        return r.json()

api = RayBotWebhooks("https://webapi.raybot.app", "api_user_id", "your_token")

webhook = api.create(
    url="https://example.com/hook",
    label="prod-alerts",
    auth_header="Bearer my-secret",
)
api.attach_addresses(webhook["id"], [{"wallet_address": "0xabc...", "wallet_name": "main"}])
print("Webhook ready:", webhook["id"])

PreviousWebhooks NextFAQ

Last updated 24 days ago

hashtag🌐 Base URL

hashtag🔐 Authentication

hashtagRate Limits

hashtagPlan gating

hashtag📋 Endpoints

hashtagList Webhooks

hashtagCreate Webhook

hashtagGet Webhook

hashtagUpdate Webhook

hashtagDelete Webhook

hashtagSend Test Delivery

hashtag🔗 Managing Addresses

hashtag🚨 Error Codes

hashtag📦 Delivery Payload

hashtag🔧 SDKs and Examples

hashtagJavaScript/Node.js Example

hashtagPython Example

🌐 Base URL

🔐 Authentication

Rate Limits

Plan gating

📋 Endpoints

List Webhooks

Create Webhook

Get Webhook

Update Webhook

Delete Webhook

Send Test Delivery

🔗 Managing Addresses

🚨 Error Codes

📦 Delivery Payload

🔧 SDKs and Examples

JavaScript/Node.js Example

Python Example