WebSocket-поток событий

Когда использовать

HTTP webhooks — основной способ: BillBill шлёт POST на ваш публичный HTTPS URL.

WebSocket — альтернатива, если:

ваш сервис не может принимать входящие HTTP из интернета (desktop-agent, VPN-only backend);
нужен постоянный канал без настройки endpoint’ов и фильтрации событий.

WebSocket доставляет все события мерчанта (без фильтра по типу, в отличие от HTTP endpoint’ов).

В админке: Configuration → Webhook → WebSocket event stream.
Скопируйте connection URL (полный token показывается один раз — при первой ротации или после Rotate token).
Подключитесь к API:


wss://<api-host>/merchant_ws?token=<websocket_token>

Token не связан с Open API keys и не связан с webhook signing secret.

Способ	Статус
`?token=<websocket_token>`	Рекомендуется
`/merchant_ws/{credential}`	Legacy; credential = websocket token или устаревший `merchant.api_key`

Сервер шлёт JSON text frames (не binary):


{
  "id": 12345,
  "merchantId": 1,
  "webhookEvent": "subscription.created",
  "data": { ... },
  "createTime": 1713348000
}

Периодически приходит WebSocket ping для keep-alive.

События пишутся в очередь при каждом billing-событии (параллельно с HTTP webhooks).
Пока клиент подключён, сервер опрашивает очередь (~100 ms) и отправляет pending-сообщения.
После успешной отправки сообщение помечается доставленным; при обрыве соединения непрочитанные события будут отправлены при следующем подключении.

Храните token как секрет (env / secret manager).
Rotate token в админке при компрометации — старые соединения перестанут авторизоваться.
Используйте wss:// в production.

Метод	Путь	Описание
`GET`	`/merchant/webhook/websocket_config`	Masked token + URL prefix
`POST`	`/merchant/webhook/rotate_websocket_token`	Новый token и полный connection URL (один раз)