Skip to main content

Обзор

Бот предоставляет две системы для real-time обновлений:
  1. WebSocket — для real-time обновлений в веб-админке
  2. Webhooks — для отправки событий во внешние системы

WebSocket

Подключение

WebSocket endpoint: ws://your-api-host:port/ws Авторизация через query-параметр:
const ws = new WebSocket('ws://localhost:8080/ws?token=YOUR_API_TOKEN');
// или
const ws = new WebSocket('ws://localhost:8080/ws?api_key=YOUR_API_TOKEN');

Формат сообщений

Подтверждение подключения:
{
  "type": "connection",
  "status": "connected",
  "message": "WebSocket connection established"
}
Событие:
{
  "type": "user.created",
  "payload": {
    "user_id": 123,
    "telegram_id": 456789,
    "username": "testuser",
    "first_name": "Test"
  },
  "timestamp": "2025-01-15T10:30:00"
}
Keepalive (ping/pong):
// Отправить
{ "type": "ping" }
// Ответ
{ "type": "pong" }

Поддерживаемые события

СобытиеОписание
user.createdСоздан новый пользователь
payment.completedЗавершён платёж
transaction.createdСоздана транзакция
ticket.createdСоздан тикет
ticket.status_changedИзменён статус тикета
ticket.message_addedНовое сообщение в тикете

Webhooks

Создание webhook

POST /webhooks
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "name": "My Webhook",
  "url": "https://example.com/webhook",
  "event_type": "user.created",
  "secret": "optional-secret-for-signing",
  "description": "Webhook для новых пользователей"
}

Поддерживаемые события

  • user.created — создан новый пользователь
  • payment.completed — завершён платёж
  • transaction.created — создана транзакция
  • ticket.created — создан тикет
  • ticket.status_changed — изменён статус тикета

Заголовки запроса

ЗаголовокОписание
Content-Typeapplication/json
X-Webhook-EventТип события (например, user.created)
X-Webhook-IdID webhook
X-Webhook-SignatureHMAC-SHA256 подпись (если указан secret)

Подпись payload

Если при создании webhook указан secret, payload подписывается HMAC-SHA256:
import hmac
import hashlib

signature = hmac.new(
    secret.encode('utf-8'),
    payload_json.encode('utf-8'),
    hashlib.sha256
).hexdigest()
# Заголовок: X-Webhook-Signature: sha256={signature}

API эндпоинты

МетодEndpointОписание
GET/webhooksСписок webhooks
GET/webhooks/{id}Получить webhook
PATCH/webhooks/{id}Обновить webhook
DELETE/webhooks/{id}Удалить webhook
GET/webhooks/statsСтатистика
GET/webhooks/{id}/deliveriesИстория доставок

Статусы доставки

  • pending — ожидает отправки
  • success — успешно доставлен (HTTP 200-299)
  • failed — ошибка доставки

Безопасность

  1. WebSocket: Требует валидный API токен
  2. Webhooks: Используйте HTTPS, подписывайте payload через secret, проверяйте подпись на стороне получателя