Исходящие вебхуки

Назначение

Ваш сервер получает HTTP POST от BillBill при изменениях в подписках, счетах, платежах, пользователях и метриках. Так вы синхронизируете состояние с CRM, биллингом внутри продукта и доступом к фичам.

Настройка

1. Реализуйте HTTPS endpoint (ответ success в теле или HTTP 200 — см. ниже).
2. В админке или через API создайте webhook endpoint (webhookNewEndpoint в MerchantApi).
3. Укажите список типов событий (строки через разделитель в модели мерчанта — см. API).
4. Сохраните signing secret, который возвращается один раз при создании endpoint (или после ротации через webhookRotateEndpointSecret).

Проверка подписи

Каждый запрос содержит заголовки:

Пример на Go:

mac := hmac.New(sha256.New, []byte(signingSecret))
mac.Write([]byte(timestamp))
mac.Write([]byte("."))
mac.Write(rawBody)
expected := hex.EncodeToString(mac.Sum(nil))
// сравните с заголовком X-BillBill-Signature (constant-time)

Рекомендуется отклонять запросы старше 5 минут по X-BillBill-Timestamp.

Заголовок Authorization не используется — для верификации нужен только signing secret endpoint’а.

WebSocket (альтернатива)

Если публичный HTTPS endpoint недоступен, можно получать все события через постоянное WebSocket-соединение. Подробнее: WebSocket-поток событий.

Каталог событий

Полный перечень констант в коде API — в ListeningEventList; человекочитаемый список с рекомендуемыми действиями — на странице События вебхуков.

Рекомендации по обработке

• Отвечайте быстро (десятки–сотни мс); тяжёлую работу выносите в очередь.
• Тело ответа должно содержать строку success (иначе BillBill повторит доставку).
• Учитывайте повторные доставки: храните eventId / пару (тип, идентификатор сущности, время) для идемпотентности.
• Логируйте сырое тело для отладки (без персональных данных в открытом виде в незащищённых логах).

Тестирование

В админке доступны логи доставки вебхуков; через API — повторная отправка (webhookResend).