Вебхуки

Что такое вебхук и для чего он нужен

Вебхук (Webhook) — это механизм автоматической отправки уведомлений из нашего сервиса в вашу систему (CRM, ERP, 1С, собственное приложение и т. п.) при наступлении определённых событий посредством HTTP(S) запросов.

Вместо того чтобы регулярно опрашивать API (например, проверять статус доставки SMS), ваш сервер получает HTTP(S)-запрос в момент, когда событие действительно произошло.

Использование вебхуков позволяет:

• получать данные практически в реальном времени;
• снизить нагрузку как на вашу систему, так и на API сервиса;
• упростить архитектуру интеграции;
• точно отслеживать итоговые статусы доставки SMS или события форм, такие как отправка, подтверждение контакта или отписка.

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

На данный момент доступны следующие типы событий:

• События форм — передаются данные, введённые пользователем в форму, а так же оповещение при подтверждении номера телефона или email-адреса, или при отписке от формы.
• Статусы SMS — передаётся окончательный статус доставки SMS абоненту.

Как создать вебхук

Шаг 1. Переход к настройкам

Перейдите в Панель управления → API → Вебхуки и нажмите кнопку «Создать вебхук». Откроется форма создания нового вебхука.

Шаг 2. Настройка параметров

В форме создания вебхука укажите следующие параметры:

Тип события

Определяет событие в системе Mobizon, при наступлении которого будет отправляться вебхук.

Доступные варианты:

• События форм
• Статусы SMS

Формат передачи данных

Формат, в котором данные вебхука будут отправляться на ваш сервер:

• raw
• xml
• json

Выбирайте формат в зависимости от возможностей вашего обработчика.

Адрес обработчика

URL, на который будут отправляться вебхуки.

Ограничения:

• максимальная длина URL — до 1000 символов;
• запросы отправляются только методом POST;
• допускается не более одного серверного редиректа (HTTP 301 или 302).

Важно:

• поддерживаются только серверные редиректы;
• цепочки редиректов не поддерживаются;
• при превышении одного редиректа уведомление считается недоставленным.

Секретный ключ

Секретный ключ используется для проверки подлинности запроса.

Особенности:

• может содержать любой набор символов;
• максимальная длина — 255 символов;
• не передаётся в HTTP-запросе;
• используется только для формирования и проверки подписи.

Если секретный ключ не задан:

• подпись запроса не формируется;
• безопасность обработчика необходимо обеспечивать другими способами (например, ограничением доступа к URL).

Активность вебхука

Установите флаг «Активен», если вебхук должен начать работу сразу после создания.

Шаг 3. Сохранение

Нажмите кнопку «Сохранить». Созданный вебхук появится в списке.

Особенности работы вебхуков

• Вебхук отправляется на одно SMS-сообщение целиком, а не на каждый его сегмент.
• Уведомления отправляются только при получении конечного статуса доставки SMS.
• Можно создавать несколько вебхуков для одного типа события.
• Каждый вебхук получает события по всем SMS и формам вашего аккаунта.
• Запрос считается успешно доставленным, если сервер обработчика вернул HTTP-код 200–299 не позднее чем через 5 секунд.
• Если ответ не получен за 5 секунд или возвращён код вне диапазона 200–299, система выполнит повторную отправку.

Повторные попытки доставки:

• выполняется до 10 попыток;
• интервал между попытками увеличивается на 1 минуту с каждой новой попыткой;
• после исчерпания попыток событие считается недоставленным.

Структура запроса вебхука

Все вебхуки отправляются HTTP(S)-запросом методом POST.

Поля верхнего уровня

Пример payload: статус доставки SMS (sms-delivery-report)

{
  "eventId": 26,
  "eventType": "sms-delivery-report",
  "eventCreateTs": "2026-01-15 11:42:28",
  "webhookId": 1,
  "attempt": 1,
  "data": {
    "campaignId": 245455096,
    "messageId": 169275418,
    "segNum": 3,
    "statusUpdateTs": "2026-01-15 11:42:08",
    "status": "DELIVRD",
    "to": "380737893456"
  },
  "sign": "3f0a37cf5e27fe0615504b6d700b4b657ecfd39d"
}

Поле data

Примеры payload: события форм

Вебхуки для форм могут отправляться при различных действиях пользователя: отправке формы, подтверждении контакта или отписке.

Отправка формы (form-submission)

Событие отправляется сразу после успешного заполнения и отправки формы пользователем.

{
  "eventId": 40,
  "eventType": "form-submission",
  "eventCreateTs": "2026-01-15 16:53:30",
  "webhookId": 1,
  "attempt": 1,
  "data": {
    "formId": 846,
    "submissionId": 3680,
    "items": [
      {
        "submissionDataId": 12303,
        "fieldId": 3744,
        "fieldType": "TEXT_STRING",
        "fieldName": "Name",
        "value": "Ivan"
      },
      {
        "submissionDataId": 12304,
        "fieldId": 3745,
        "fieldType": "EMAIL",
        "fieldName": "E-mail",
        "value": "test@mobizon.com",
        "confirmationRequired": 1
      },
      {
        "submissionDataId": 12305,
        "fieldId": 3746,
        "fieldType": "MOBILE",
        "fieldName": "Celular",
        "value": "380737893456",
        "confirmationRequired": 1
      }
    ]
  },
  "sign": "0a38941c47689e3cb3634db817cd4851d2511c47"
}

Описание поля items

Каждый элемент массива соответствует одному полю формы.

Подтверждение контакта (form-contact-confirmation)

Событие отправляется после подтверждения пользователем email-адреса или номера телефона с помощью кода в SMS или Email.

{
  "eventId": 42,
  "eventType": "form-contact-confirmation",
  "eventCreateTs": "2026-01-15 16:54:15",
  "webhookId": 1,
  "attempt": 1,
  "data": {
    "formId": 846,
    "submissionId": 3680,
    "item": {
      "submissionDataId": 12305,
      "fieldId": 3746,
      "fieldType": "MOBILE",
      "fieldName": "Celular",
      "value": "380737893456",
      "confirmationTs": "2026-01-15 16:54:14"
    }
  },
  "sign": "fe0da5443a9f5cadd0e972301415816cec481137"
}

Отписка контакта от формы (form-contact-unsubscribe)

Событие отправляется, если пользователь отписался через форму отписки.

{
  "eventId": 45,
  "eventType": "form-contact-unsubscribe",
  "eventCreateTs": "2026-01-15 17:33:47",
  "webhookId": 1,
  "attempt": 1,
  "data": {
    "formId": 846,
    "unsubscribeTs": "2026-01-15 17:33:46",
    "items": [
      {
        "submissionId": 3675,
        "submissionDataId": 12289,
        "fieldId": 3745,
        "fieldType": "EMAIL",
        "fieldName": "E-mail",
        "value": "test@mobizon.com",
        "confirmationTs": ""
      }
    ]
  },
  "sign": "06b78cf55ad19f9810babc415e86535384b74663"
}

Проверка подлинности запроса

Для проверки используется поле sign, вычисляемое по алгоритму SHA1.

Формирование подписи

Строка для подписи формируется в следующем порядке:

eventId|attempt|eventCreateTs|secretKey

Где secretKey — секретный ключ, указанный при создании вебхука.

Пример проверки подписи на PHP

$secretKey = 'secret123';

$payload = json_decode(file_get_contents('php://input'), true);

$hash = sha1(
    $payload['eventId'] . '|' .
    $payload['attempt'] . '|' .
    $payload['eventCreateTs'] . '|' .
    $secretKey
);

if (hash_equals($hash, $payload['sign'])) {
    http_response_code(200);
} else {
    http_response_code(403);
}

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

• Один и тот же вебхук может быть отправлен несколько раз (при повторных попытках доставки).
• Рекомендуется сохранять eventId и не обрабатывать одно и то же событие повторно.
• Не выполняйте длительные операции при обработке запроса.
• Оптимальный сценарий:
  • проверить подпись;
  • сохранить событие;
  • быстро вернуть HTTP 200;
  • выполнить дальнейшую обработку асинхронно.

Частые ошибки

Итог

Вебхуки позволяют получать данные о статусах SMS и формах:

• без постоянного опроса API;
• с минимальной задержкой;
• с гарантией повторной доставки при временных сбоях.

Корректная проверка подписи и аккуратная обработка повторных запросов обеспечивают надёжную интеграцию.