Вебхуки

Коротко: вебхук — это URL на вашей стороне, куда платформа отправляет статусы сообщений и входящие ответы от контактов.

Кому подходит

Роль: Разработчик
Уровень: Опытный

Что это

Вебхук — механизм push-уведомлений. Вместо того чтобы постоянно опрашивать API, вы получаете данные автоматически: платформа сама отправляет POST-запросы на ваш URL.

Что приходит на вебхук

Событие	Что содержит
messageStatus	Статус отправленного сообщения
message	Входящее сообщение от контакта

Где указать URL вебхука

Вебхук можно указать в трёх местах (в порядке приоритета):

Поле webhook в теле запроса — для конкретного сообщения.
Настройки имени отправителя — для всех сообщений от этого имени.
Настройки API-ключа — для всех сообщений по этому ключу.

Поля статуса сообщения

Приходит в поле message:

Поле	Что содержит
messageId	Уникальный ID сообщения
omniTransactionId	ID транзакции (может быть пустым)
channel	Номер канала
senderId	ID отправителя
status	Статус
timestamp	Время события
contact	Номер получателя
cost	Стоимость
clientInfo	Пользовательское поле

Возможные статусы

Статус	Что означает
sent	Сообщение отправлено
failed	Ошибка отправки
delivered	Сообщение доставлено
undeliverable	Не удалось доставить
displayed	Сообщение просмотрено
unknown	Неизвестный статус

Поля входящего сообщения

Приходит в поле message:

Поле	Что содержит
messageId	Уникальный ID
omniTransactionId	ID транзакции
timestamp	Время
channel	Тип канала
senderId	ID отправителя
contact	Номер отправителя
payload	Содержимое сообщения
status	Статус (может быть пустым)
webhook	URL вебхука

Как настроить

Создайте endpoint на вашей стороне, который принимает POST-запросы.
Убедитесь, что endpoint доступен из интернета.
Укажите URL в настройках API-ключа или имени отправителя.
Проверьте, что запросы приходят.

Формат запроса от платформы

Метод: POST

Тело: JSON с полями event и message.

Безопасность

Рекомендуется:

Использовать HTTPS.
Проверять источник запросов.
Логировать все входящие вебхуки.

Частые проблемы

Симптом	Причина	Решение
Вебхук не приходит	URL недоступен	Проверьте доступность
Вебхук не приходит	Firewall блокирует	Разрешите IP платформы
Дублирование	Retry-логика	Используйте messageId как ключ
Медленная обработка	Тяжёлые операции	Отвечайте 200 сразу, обрабатывайте асинхронно

См. также

Нужна помощь?

OTP-коды: support@otpcod.ru
Multi API: support@multiapi.ru
Мой диалог: support@mydialogi.ru