Вебхуки
Исходящие уведомления о событиях eSIM — подписка, доставка, подпись
Модуль notification доставляет B2B-партнёрам события по eSIM через исходящие webhook'и: telecom → endpoint партнёра. Поставщик вызывает входящие webhook-ручки сервиса; fulfilment фиксирует изменения и публикует доменные события в Kafka; notification создаёт задачу на доставку и отправляет HTTP POST на URL партнёра.
Подписка
Для аккаунтов с kind=external требуется зарегистрированная подписка через
POST /api/v1/b2b/webhooks. Аккаунт
может иметь не более одной подписки — повторный вызов вернёт 409.
Управлять подпиской можно через:
GET /api/v1/b2b/webhooks— посмотреть текущую подпискуPOST .../change-url— сменить URL endpointPOST .../rotate-secret— сменить секрет подписи (со graceful-периодом)POST .../disable/.../enable— приостановить/возобновить доставкуDELETE /api/v1/b2b/webhooks/{webhookID}— удалить подписку
Поддерживаемые события
| Событие | Когда срабатывает |
|---|---|
esim.profile.status_changed | смена статуса профиля eSIM на устройстве (установка/активация/выключение/удаление) |
esim.package.usage_threshold_reached | достигнут порог использования пакета — 20% и 80% |
esim.package.exhausted | пакет eSIM полностью исчерпан |
Тестировать интеграцию можно без реального трафика — см. Sandbox: симуляция статусов профиля и использования eSIM триггерит те же webhook-события, не меняя реальное состояние.
Доставка и повторные попытки
При недоступности endpoint партнёра сервис выполняет до 5 HTTP-попыток с
экспоненциальным backoff: начальная задержка 30 секунд, максимум 1 час между
попытками. Повторяются только временные ошибки (сеть, HTTP 5xx, 429);
HTTP 4xx — без retry, доставка считается завершённой с ошибкой на стороне
партнёра.
Заголовки исходящего запроса
| Заголовок | Значение |
|---|---|
X-Webhook-Signature | HMAC-SHA256 подпись тела, формат sha256=<hex> |
X-Everyru-Notification-Id | идентификатор notification в системе telecom |
X-Everyru-Attempt | номер попытки доставки, 1..5 |
X-Everyru-Delivery-Id | correlation id (если есть) |
Проверка подписи
Секрет для HMAC-SHA256 задаётся при создании подписки и виден только вам
(сервер его не хранит в открытом виде для ответов). Чтобы проверить
подлинность запроса: посчитайте HMAC-SHA256 от сырого JSON-тела запроса с
вашим секретом и сравните с X-Webhook-Signature (constant-time сравнение).
При ротации секрета (rotate-secret)
старый секрет остаётся валидным в течение grace-периода — принимайте подпись
по любому из двух секретов, пока grace-период не истёк.