Вебхуки

Що таке вебхук і для чого він потрібен

Вебхук (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, на який надсилатимуться вебхуки.

Обмеження:

• максимальна довжина 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": "Ім'я",
        "value": "Ivan"
      },
      {
        "submissionDataId": 12304,
        "fieldId": 3745,
        "fieldType": "EMAIL",
        "fieldName": "E-mail",
        "value": "test@mobizon.com",
        "confirmationRequired": 1
      },
      {
        "submissionDataId": 12305,
        "fieldId": 3746,
        "fieldType": "MOBILE",
        "fieldName": "Мобільний",
        "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": "Мобільний",
      "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;
• з мінімальною затримкою;
• з гарантією повторної доставки при тимчасових збоях.

Коректна перевірка підпису та акуратна обробка повторних запитів забезпечують надійну інтеграцію.