Как получать СМС через вебхук

Откройте меню аккаунта, выберите «Ключи API», перейдите на вкладку «Вебхуки» и добавьте публичный HTTPS-адрес своего сервера. После этого SMSZ будет отправлять туда каждое входящее СМС сразу после получения, и опрашивать API больше не придётся.

Обновлено 18 ноября 2026 г.

Вебхук — это адрес на вашем сервере, который SMSZ вызывает, когда в аккаунте что-то происходит. Каждое сообщение приходит к вам сразу, с подписью и с теми же данными, что возвращает API. Добавить адрес можно и без ключа API. А чтобы протестировать его или изменить список событий через API, ключ понадобится — см. как создать ключ API.

Как подключить вебхук

  1. Подготовьте на сервере адрес, который принимает POST-запросы. Он должен быть публичным и работать по HTTPS: локальные адреса вроде localhost не принимаются.
  2. Войдите, откройте меню аккаунта, выберите «Ключи API» и перейдите на вкладку «Вебхуки».
  3. Вставьте адрес в поле «Куда отправлять события» и нажмите «Добавить».
  4. Скопируйте появившийся секрет подписи. Он начинается с whsec_ и показывается только один раз. Сохраните его на сервере и нажмите «Готово, сохранено».

Адрес, добавленный здесь, получает все события; сузить список можно позже через API. В одном аккаунте может быть до 10 адресов.

В каких событиях приходят СМС

Каждая доставка — это событие в формате JSON с полем type и объектом data. Входящие СМС приходят как activation.message.received для одноразовых номеров и rental.message.received для арендованных. В data лежат номер и его сообщения: в поле text — полный текст СМС, в поле code — код, если его удалось распознать. На тот же адрес приходят и другие события, например изменение баланса, так что ненужные типы просто пропускайте.

Проверьте подпись

В каждой доставке есть заголовок SMSZ-Signature с меткой времени t и подписью v1. Посчитайте HMAC-SHA256 от строки из метки времени, точки и исходного тела запроса, взяв секрет подписи в качестве ключа, и сравните результат с v1. Проверяйте исходное тело до разбора JSON и отклоняйте старые метки времени, чтобы перехваченный запрос нельзя было отправить повторно. Готовый код на JavaScript и Python есть в руководстве по вебхукам (на английском).

Отвечайте быстро и будьте готовы к повторам

  • Ответьте любым статусом 2xx в течение 10 секунд, а долгую обработку делайте уже после ответа.
  • Если сервер не ответил 2xx, SMSZ повторит доставку — до 8 попыток в течение чуть больше суток. Перенаправления не выполняются.
  • Одно и то же событие может прийти несколько раз, а порядок событий не гарантирован. Пропускайте события, id которых вы уже обработали.
  • После 20 сбоев подряд адрес отключается, и на вкладке «Вебхуки» у него появляется метка «отключён». Исправьте сервер и нажмите «Включить».

Как проверить

Через API можно отправить тестовое событие — настоящую подписанную доставку с заведомо ненастоящими данными, — и API покажет, что ответил ваш сервер. Журнал доставок в API показывает каждую попытку и код ответа. На вкладке «Вебхуки» видны дата последней успешной доставки и число сбоев. Нет публичного сервера? Читайте те же события из списка событий в API: он хранит их 30 дней.

Потеряли секрет подписи? Удалите адрес и добавьте его заново — появится новый секрет. События, которые ещё ждали отправки на старый адрес, при этом пропадут.

Не нашли ответ? Напишите нам

Пишите на [email protected] или через страницу поддержки. Обычно отвечаем в течение 24 часов. Чтобы вопрос решился одним ответом, укажите в первом письме: