Вебхуки отправляют события Deskgram на указанный вами адрес: в CRM, сервис автоматизации или собственное приложение.
Актуальность: 15 октября 2026 года.
Перед началом: Deskgram должен быть запущен, а адрес получателя — доступен с компьютера, на котором работает программа. Сейчас поддерживается отправка POST-запросов с JSON. Автоматическое восстановление недоставленных запросов после перезапуска еще не реализовано.
Для настройки через интерфейс программирование не требуется. Разработчикам получателя и пользователям локального HTTP API доступен справочник API.
Содержание
- Быстрая настройка
- Что указать для CRM
- Какие события выбрать
- Как работают модули
- Как выбрать данные запроса
- Дополнительные настройки
- Как проверить подключение
- Журнал и повтор доставки
- Примеры сценариев
- Если что-то не работает
- Управление через AI-агента
- Ограничения
Быстрая настройка
- Получите URL вебхука в системе, которая будет принимать данные. Если она выдает секрет или токен, подготовьте его.
- В Deskgram откройте Настройки → Интеграции.
- Нажмите Новый, укажите название и Webhook URL.
- В разделе Какие действия отправлять выберите события.
- В разделе Из каких модулей оставьте Все модули или выберите нужные.
- В разделе Что будет в запросе выберите формат. Для первого подключения удобно начать со Стандартного JSON Deskgram, если получатель его поддерживает.
- При необходимости заполните секрет и дополнительные заголовки.
- Проверьте переключатель Включить вебхук после сохранения, нажмите Создать вебхук.
- Нажмите Проверить, затем откройте Журнал и детали доставки.
- Выполните короткое реальное действие, соответствующее выбранному событию, и проверьте результат у получателя.
Проверить отправляет запрос с сохраненными настройками. После изменения URL, секрета, событий или полей сначала нажмите Сохранить.
Вы можете создать несколько вебхуков с разными адресами, событиями и форматами.
Что указать для CRM
В поле URL укажите входящий адрес вебхука CRM, а не адрес ее главной страницы или кабинета.
Например, входящий адрес совместимого канала Deskgram может выглядеть так:
https://crm.example.com/api/v1/channel-webhooks/deskgram/123Здесь домен и номер канала приведены для примера. Используйте адрес из вашей CRM.
| Настройка | Что выбрать |
|---|---|
| Название | Понятное вам имя: например, «CRM: сообщения рассылки» |
| Webhook URL | Полный адрес, выданный CRM |
| Секрет CRM | Секрет именно этого канала, если CRM его требует |
| Формат | Для совместимого канала Deskgram начните со стандартного JSON |
| Модуль | Для событий рассылки — spam_pm |
| События | Отправка сообщения, ошибка отправки, ответ лида — по вашему сценарию |
| Включение | Вебхук должен быть включен для автоматической отправки |
Deskgram распознает адреса вида /channel-webhooks/deskgram/{id} и показывает поле Секрет CRM. В запросе секрет передается в заголовке x-secret. Полный адрес и секрет выдаются CRM отдельно; их нельзя получить из одного только URL.
Для другой CRM уточните ее требования к JSON и авторизации. Формат CRM-лид не является универсальным адаптером ко всем CRM: названия полей должны совпадать с требованиями конкретного получателя.
Для n8n, Make, Zapier или собственного API используется тот же принцип: вставьте адрес принимающего шага и настройте ожидаемые поля. Входящий шаг сценария должен быть включен и доступен.
Какие события выбрать
| Название в интерфейсе | Идентификатор | Когда приходит |
|---|---|---|
| Задача завершена | task.completed | Завершилась обработка задачи |
| Задача завершилась ошибкой | task.failed | Задача получила финальный статус ошибки |
| Задача остановлена | task.cancelled | Задача остановлена или отменена |
| Сообщение отправлено | message.sent | В рассылке spam_pm зафиксирована отправка сообщения |
| Ошибка отправки сообщения | message.failed | В spam_pm зафиксирована поддерживаемая ошибка доставки |
| Получен ответ лида | lead.reply_received | В spam_pm зафиксирован входящий ответ |
Для передачи каждого сообщения в CRM выберите события сообщений. Одно событие Задача завершена не создает отдельный запрос на каждое отправленное сообщение.
Финальное завершение задачи само по себе не означает, что все действия внутри нее успешны. Итоговые счетчики и ошибки зависят от модуля и находятся в данных результата.
Ошибка разрешения получателя или пропуск сообщения не обязательно создают message.failed: события пропусков сейчас не входят в список вебхуков.
Для ответа лида Deskgram должен получить входящее сообщение через работающий механизм обработки ответов. Создание вебхука само по себе не включает постоянное прослушивание аккаунтов и не гарантирует сбор ответов после окончания задачи.
Кнопки выбора:
- Результаты задач выбирает три финальных события.
- Все доступные выбирает все шесть поддерживаемых событий.
- Очистить снимает выбор; перед сохранением выберите нужные события.
Как работают модули
Фильтр модуля отвечает на вопрос: «Из каких задач брать выбранные события?»
- Все модули — не ограничивать отправку конкретным модулем.
- Выбрать модули — отправлять события только из выбранных разделов.
Например, task.completed + spampm — завершение рассылки в личные сообщения; message.sent + spampm — отдельные отправленные сообщения этой рассылки.
Выбор модуля не добавляет ему новые виды событий. Живые события сообщений и ответов сейчас подключены к spam_pm. Выбор другого модуля для message.sent не включает передачу его сообщений.
Как выбрать данные запроса
| Формат | Назначение |
|---|---|
| Стандартный JSON Deskgram | Полное событие с вложенными данными задачи, лида или сообщения |
| Краткий результат | Редактируемый набор полей для статуса, контакта, сообщения и ошибки |
| CRM-лид | Редактируемые плоские поля лида и сообщения |
| Своя схема | Поля с вашими названиями и выбранными источниками данных |
Точный состав запроса зависит от события и сохраненного набора полей. Смотрите предпросмотр, затем фактические отправленные данные в деталях доставки.
Настройка своих полей
Для каждого поля задайте:
- Слева — имя поля, которое ожидает получатель.
- Справа — источник данных Deskgram.
- Переключателем — включено ли поле.
Например, вашей CRM нужны contact.telegram_id, contact.username и comment:
| Поле у получателя | Источник Deskgram |
|---|---|
contact.telegram_id | lead.telegramuserid |
contact.username | lead.username |
comment | message.text |
Пример результата для события сообщения:
{ "contact": { "telegram_id": "123456789", "username": "example_client" }, "comment": "Здравствуйте!"}Точка в имени поля создает вложенный объект. Если у источника нет значения, поле не добавляется. Например, телефон может отсутствовать: вебхук не делает скрытый номер доступным.
Если выключить или удалить все поля, будет отправлен пустой объект {}. Полное событие вместо него не подставляется.
Предпросмотр содержит пример, а не данные конкретного получателя вашей будущей рассылки. Фактический запрос может иметь меньше полей.
Дополнительные настройки
| Поле | Когда нужно |
|---|---|
| Secret для подписи | Получатель требует общий секрет или проверку HMAC |
| Headers JSON | Получатель требует дополнительные HTTP-заголовки, например Authorization |
| Timeout, сек | Ограничение ожидания ответа; по умолчанию 15 секунд, в интерфейсе 3–60 |
Пример дополнительных заголовков:
{ "Authorization": "Bearer YOUR_RECEIVER_TOKEN"}YOURRECEIVERTOKEN — обозначение токена вашей принимающей системы, а не ключа лицензии Deskgram.
При редактировании пустое поле сохраненного секрета в интерфейсе сохраняет прежний секрет. Значение повторно не показывается.
Если задан Secret, Deskgram добавляет x-secret, X-Deskgram-Webhook-Secret и X-Deskgram-Signature. Подпись позволяет получателю проверить тело запроса. Пример проверки приведен в справочнике API.
Как проверить подключение
Кнопка Проверить отправляет специальное событие webhook.test выбранному получателю. Его можно отправить и выключенному вебхуку.
Тест проверяет HTTP-подключение и обработку тестового запроса. Он не запускает Telegram-задачу и не содержит реального лида. Если выбран собственный формат, он применяется и к тесту; недоступные поля лида будут отсутствовать.
Получатель должен уметь принимать тестовые события. Отказ CRM на тест без лида может быть особенностью ее проверки: смотрите код ответа и тело ошибки.
Успешной считается доставка с HTTP-кодом 200–299. В частности, 302 не означает успешную доставку: переход по перенаправлению не выполняется.
HTTP 200 означает, что запрос принят по HTTP, но не доказывает создание лида или сообщения. Проверьте ответ CRM и соответствующую запись в ней.
Журнал и повтор доставки
Журнал показывает последние доставки. Можно выбрать получателя и статус, затем нажать Журнал, чтобы обновить список.
| Статус | Значение |
|---|---|
pending | Запись создана, результат еще не зафиксирован |
retrying | Доставка не удалась, идет автоматический повтор |
success | Получен HTTP-ответ 200–299 |
error | Попытки исчерпаны или отправка завершилась ошибкой |
В деталях доступны отправленные данные, исходное событие для новых доставок, ответ получателя, ошибка, число попыток и даты.
Автоматические повторы
На доставку выполняется до трех попыток. Паузы перед второй и третьей попыткой составляют примерно 2 и 4 секунды, не считая ожидания сети. Повторяются также ответы 4xx и 5xx.
Все автоматические попытки одной доставки используют один X-Deskgram-Delivery-Id. Получателю следует проверять этот идентификатор, чтобы не создавать дубликаты.
Ручной повтор
- Откройте ошибочную доставку.
- Исправьте URL, секрет или нужные поля у ее вебхука.
- Нажмите Сохранить.
- Вернитесь к ошибочной записи и нажмите Повторить доставку.
- Проверьте новую запись в журнале и результат у получателя.
Ручной повтор доступен только для error. Он создает новую доставку с новым идентификатором; старая запись сохраняется.
Для новых доставок повтор использует исходное событие и актуальные настройки формата. У старых записей без исходного события повторяется сохраненный JSON без повторного преобразования. Актуальные URL, секрет и заголовки используются в обоих случаях.
Если получатель уже обработал запрос, но ответ потерялся, повтор может создать дубликат. Ручной повтор с новым ID требует проверки бизнес-дубликатов на стороне CRM.
Отключение вебхука прекращает выбор для новых автоматических событий, но не отменяет уже начавшийся запрос. Явные Проверить и Повторить могут отправить запрос выключенному вебхуку. После удаления вебхука история остается, но повтор невозможен.
Примеры сценариев
Передать сообщения рассылки в CRM
Выберите spampm и события message.sent, message.failed, lead.replyreceived. Для совместимого канала Deskgram используйте стандартный JSON и секрет канала.
Отправьте одно сообщение на свой тестовый аккаунт, ответьте на него и проверьте обе доставки и обе записи у получателя.
Запустить сценарий после окончания задачи
Выберите task.completed и нужный модуль. Передайте стандартный JSON или краткий результат.
Если автоматизация должна обрабатывать также неуспешные запуски, дополнительно выберите task.failed и task.cancelled.
Принимать данные в собственном приложении
Задайте входящий адрес, согласуйте поля, настройте Secret и сохраните вебхук. Приложение должно принимать POST с JSON, проверять подпись и возвращать 2xx после надежного приема данных.
Полный HTTP-контракт и пример HMAC-проверки: справочник для разработчика.
Если что-то не работает
| Симптом | Что проверить |
|---|---|
| При рассылке нет новых записей | Вебхук сохранен и включен; выбрано событие сообщения; фильтр включает spam_pm; обновлен журнал |
| Приходит только завершение задачи | Выбрано только task.completed; добавьте события сообщений и сохраните |
| Ответ лида не приходит | Deskgram получил ответ через активный обработчик; выбран lead.reply_received |
| Кнопка «Проверить» недоступна | Новый вебхук еще не сохранен или другой тест уже выполняется |
| HTTP 401 или 403 | Секрет канала, Authorization и права на стороне получателя |
| HTTP 404 | Полный входящий URL, путь и номер канала |
| HTTP 301 или 302 | Укажите конечный URL без перенаправления |
| HTTP 400 или 422 от получателя | Откройте отправленный JSON и ответ; сравните поля с требованиями получателя |
| Успех, но лида нет | Проверьте тело ответа CRM; тестовое или task-событие может не содержать данных для создания лида |
| Уходит пустой JSON | Нет включенных полей либо источники отсутствуют у выбранного события |
| Приходит старый формат | Изменения не сохранены; у старой delivery может не быть source_payload |
| Ошибка подключения или timeout | Доступность адреса с этого компьютера, DNS, сертификат, настройки сети и timeout |
| Повтор недоступен | Запись не error, получатель удален или уже выполняется другой ручной повтор |
| Агент отклоняет localhost/HTTP URL | Для MCP-подключений разрешен только публичный HTTPS |
Управление через AI-агента
Вебхуками можно управлять через отдельные MCP-инструменты при включенном пользователем разрешении в Настройки → MCP.
У этого режима есть отличия:
- Создание по умолчанию выполняется в dry-run; новый endpoint по умолчанию выключен.
- Требуется публичный HTTPS-адрес; localhost, LAN и HTTP не поддерживаются.
- После создания, редактирования, включения, тестирования или повтора через MCP защищенные сетевые правила сохраняются для дальнейших отправок такого вебхука.
- Правила не снимаются обычным редактированием в интерфейсе или выключением MCP.
- Агент не получает сохраненный секрет, значения заголовков и полные тела доставок через инструменты чтения.
Для ручного отключения/удаления и чтения существуют отдельные правила. Подключение AI-агента описано в обзоре MCP.
Ограничения
- Это исходящие уведомления о событиях, а не способ удаленно запустить произвольное действие Deskgram.
- История в базе не является сохраняемой очередью: доставка, прерванная закрытием программы, автоматически после запуска не возобновляется.
- Постоянный входящий канал команд от CRM этим механизмом не создается.
- Поддерживается POST с JSON; GET, multipart и произвольный текст тела не настраиваются.
- Конструктор выбирает и переименовывает поля, но не выполняет JavaScript, вычисления, поиск значений в CRM или цепочки HTTP-запросов.
- Вебхуки не гарантируют единственную доставку и порядок поступления разных событий.
- Состав результата задачи зависит от модуля. Получатель должен учитывать отсутствующие поля.
- В данных могут быть контакты, тексты сообщений, параметры задачи и результаты. Выбирайте получателя и поля с учетом того, что эти данные уйдут во внешнюю систему.