Вебхук — это способ передать заявку из квиза туда, где нет готовой интеграции: в самописную CRM, внутреннюю систему учёта или сервис, которого пока нет в каталоге Matomba. По сути, вебхук — это мост между вашим квизом и любым внешним адресом, который умеет принимать JSON.
Вы можете настроить получение заявок в самописную CRM или отсутствующий в списке интеграций сервис используя вебхуки. Укажите до 5 ссылок, по которым будут передаваться параметры сделки и контакта. Данные передаются в формате json в закодированном через json_encode виде. Массив состоит из следующих параметров:
- service - название сервиса с которого пришла заявка;
- quiz - идентификатор квиза;
- action - тип действия: add - добавление, update - обновление;
- visit - идентификатор заявки в системе Matomba;
- raw - идентификаторы вопросов и ответов: q - содержит название вопроса, а - массив ответов;
- answers - ответы и вопросы в текстовом формате: q - содержит название вопроса, а - массив ответов;
- results - массив с выбранными результатами. Каждый элемент массива содержит следующие параметры: id(идентификатор товара), name(название товара), cost(стоимость), count(количество), currency (валюта) и discount(размер скидки);
- contacts - name (имя), phone(Телефон), mail,more - дополнительное поле, social - массив содержащий список социальных сетей контакта (vkontakte, telegram, facebook, messenger, whatsapp, skype, viber);
- cookies - roistat_visit, calltouch ID, _ga - идентификатор визита в GA, _ym_uid - идентификатор визита в яндекс метрике;
- extra - содержит referer(страница перехода к квизу), open(страница открытия квиза);
- agree - список отмеченных клиентом согласий в форме обратной связи. Работает только с кастомными политиками;
- массив utm с параметрами utm_source, utm_medium, utm_campaign, utm_term, utm_content;
- created - дата создания сделки в формате unix timestamp.
Скрипт хука должен обязательно отдавать положительный статус при приёме заявок (20* - 200, 204 и т.п.)
Зачем нужен вебхук, если есть готовые интеграции
В каталоге Matomba больше 20 nocode-интеграций, и большинству пользователей их хватает. Вебхук нужен в трёх случаях.
- У вас своя система. Готовая интеграция не подойдёт, а вручную разбирать JSON — единственный способ передать данные.
- Нужна промежуточная логика. Например, сначала проверить заявку на дубликат, потом распределить по отделам, а затем записать в CRM.
- Нужно получать копию заявок на собственном сервере — для аналитики, аудита или как страховку от потери данных.
Если вы просто хотите передавать заявки в популярную CRM, начните с готовой интеграции — это быстрее. Вебхук подключайте, когда готовой связки нет или она не покрывает задачу.
Как устроена передача данных
Когда посетитель отправляет форму, Matomba формирует JSON-объект со всеми данными заявки и отправляет его методом POST на каждый из указанных вами адресов. Серверная часть Matomba делает это асинхронно, поэтому форма на стороне пользователя отвечает мгновенно и не ждёт, пока ваш сервер примет данные.
Если ваш скрипт вернул статус из группы 20*, Matomba считает передачу успешной и больше не повторяет её. Если вернулся 4xx или 5xx, либо сервер не ответил вовремя — попытка считается неудачной. Логика повторных попыток может настраиваться на стороне интеграции, поэтому не стоит рассчитывать, что заявка придёт «вторым заходом».
Пример запроса на вебхук
{
"service": "Квиз номер один",
"app": 15123123,
"visit": 1222,
"action": "add",
"raw": [
{
"q": 1234151212313,
"a": [
7237218641244,
12412948124121
]
}
],
"answers": [
{
"q": "Вопрос номер один",
"a": [
"Ответ номер один",
"Ответ номер 2"
]
}
],
"results": [
{
"id": 123123123123,
"name": "товар номер один",
"cost": 200000,
"count": 1,
"discount": 1000,
"currency": "RUB"
}
],
"contacts": {
"phone": 79241231212,
"mail": "test@mail.ru",
"name": "Николай",
"social": {
"vkontakte": "id124124124"
}
},
"cookies": {
"roistat_visit": 12312441421412,
"_ga": "galigg.231232112_21323"
},
"extras": {
"referer": "https://yandes.com",
"open": "https://mypage.ru/11",
"utm": {
"utm_source": "cpc",
"utm_campaign": "template1"
}
},
"agree": [
{
"id": 11231231221,
"name": "Мое согласие",
"about": "Согласие на отправку рекламных акций"
}
],
"created": 18928288892
}Код для получения данных
$data = json_decode(file_get_contents('php://input'), true);
$answers = $data['answers'];
$phone = $data['contacts']['phone'];
$email = $data['contacts']['email'];
$name = $data['contacts']['name'];
$social = $data['contacts']['social'];
$createdDate = $data['created'];
$utm = $data['extra']['utm'];
$agree = $data['agree'];
$rawAnswers = $data['raw'];
// Ваш код
http_response_code(200);
exit;Как отладить передачу
Прежде чем писать логику обработки, стоит убедиться, что данные вообще доходят до вашего скрипта. Простой способ — записать входящий JSON в файл.
$raw = file_get_contents('php://input');
file_put_contents(__DIR__ . '/webhook.log', $raw . PHP_EOL, FILE_APPEND);
http_response_code(200);
exit;Отправьте тестовую заявку из квиза и посмотрите файл `webhook.log`. Если он пустой — запросы не доходят: проверьте URL, доступность сервера и настройки файрвола. Если JSON есть — значит данные приходят, и можно переходить к логике.
Проверка на своей стороне
Перед тем как сохранять данные, полезно убедиться, что пришёл валидный JSON.
$raw = file_get_contents('php://input');
$data = json_decode($raw, true);
if (json_last_error() !== JSON_ERROR_NONE) {
http_response_code(400);
exit;
}
// Ваш код
http_response_code(200);
exit;Если вернуть код 400, Matomba поймёт, что заявка не принята. Это лучше, чем молча вернуть 200 и потерять данные.
Частые ошибки при настройке вебхука
- Скрипт возвращает 200 молча, но данные не сохраняет. Matomba считает заявку переданной и повторно её не отправит. Всегда логируйте или сохраняйте входящие данные.
- Сервер недоступен по HTTPS или отвечает слишком долго. Проверьте сертификат домена и время ответа — обычно ожидание ограничено несколькими секундами.
- В ответе есть HTML или echo перед заголовком. Даже один пробел перед `
- Забыли про кодировку. Если в данных есть русские буквы, сохраняйте их в UTF-8, иначе получите искажённые символы.
- URL вебхука открыт для всех. Кто угодно может отправить POST на ваш скрипт. Добавьте проверку токена или подписи, чтобы принимать только заявки от Matomba.
Безопасность
Вебхук — это открытый endpoint на вашем сервере, и его безопасность — ваша зона ответственности. Минимальные меры: использовать HTTPS, не выводить данные в ответ, ограничить доступ по IP или токену, проверять размер входного запроса и логировать входящие данные.
Не доверяйте слепо данным из вебхука. Если значение используется в SQL, экранируйте его или используйте подготовленные запросы. Если данные идут в HTML — применяйте htmlspecialchars. Если передаёте их дальше по API — валидируйте.
Коротко: что делать
- Укажите до 5 URL вебхука в настройках интеграции.
- Принимайте POST и декодируйте JSON через file_get_contents('php://input').
- Сразу возвращайте 200 при успешной обработке — иначе Matomba будет считать передачу неудачной.
- Логируйте входящие данные на первом этапе, чтобы убедиться, что они вообще доходят.
- Добавьте проверку токена или подписи, чтобы вебхук не мог использовать кто угодно.
- Валидируйте входящий JSON и экранируйте данные перед записью в БД или рендером в HTML.
