Вебхуки

#Что понадобится

• Адрес вашего сервера, который начинается с https://.
• Роль «Администратор» или «Владелец». Остальные не видят раздел в меню, а по прямой ссылке Sender покажет «Вебхуки доступны администраторам».

#Подключить вебхук

Отдельной кнопки проверки нет: подпишитесь сами на свою группу подписчиков — и вызов появится в журнале. Журнал показывает последние 100 вызовов и сам обновляется каждые 15 секунд. В него же попадают вызовы из ботов — действие «Вебхук» в шаге бота.

#Поля вебхука

В одном канале — до 20 вебхуков. События приходят о подписке и отписке от любой группы подписчиков канала.

#Что приходит на ваш сервер

При методе «POST JSON» Sender отправляет такой JSON:

{
  "type": "subscribe",
  "secret": "секрет этого вебхука",
  "subscription_id": 12,
  "object": {
    "vk_user_id": 123456,
    "first_name": "Анна",
    "last_name": "Петрова",
    "sex": 1,
    "bdate": "1995-05-12",
    "city_id": 1,
    "country_id": 1,
    "relation": 0,
    "utms": {"utm_source": "vk"},
    "ref": "promo",
    "subscriptions": [12, 15],
    "tags": [3],
    "vars": {"phone": "+79001234567"},
    "vk_group_id": 1234567,
    "group_id": 42,
    "unixtime": 1760520600,
    "date": "2026-10-15T09:30:00.512345+00:00"
  }
}

• type — событие: subscribe (подписка) или unsubscribe (отписка);
• subscription_id — номер группы подписчиков;
• object — данные подписчика: ID, имя, пол, город, UTM-метки, код ссылки, все его группы подписчиков, метки и переменные;
• unixtime и date — когда Sender отправил вызов; date — по UTC, а не по Москве.

При «POST form-data» те же поля приходят полями формы, а object — строкой JSON. При «GET» весь JSON приходит в параметре payload.

#Как убедиться, что запрос от Sender

В каждом запросе есть поле secret — секрет этого вебхука. Скопируйте его в меню строки вебхука (кнопка «⋯» → «Копировать секрет подписи») и сохраните на своём сервере. Пришёл запрос с другим secret — это не Sender, такой запрос нужно отклонить.

#Ответ вашего сервера

• Sender ждёт ответ до 15 секунд. Не дождался — в журнале будет «Сервер не ответил за 15 с».
• Повторов нет: если сервер был недоступен, это событие не придёт снова. Пропущенное можно найти в базе подписчиков или через API.
• Можно ответить JSON со списком vars — Sender запишет эти переменные подписчику, а glob_vars — в глобальные переменные канала:

{"vars": [{"n": "crm_id", "v": "A-1024"}], "glob_vars": [{"n": "last_lead", "v": "Анна"}]}

Если подписок много, Sender отправляет не больше 20 вызовов в секунду на проект, остальные — с небольшой задержкой.

#Частые вопросы