---
title: Вебхуки
description: Вебхуки — как получать статусы доставки и входящие сообщения
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

# Вебхуки

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

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

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

## Что это

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

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

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

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

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

1. **Поле webhook в теле запроса** — для конкретного сообщения.
2. **Настройки имени отправителя** — для всех сообщений от этого имени.
3. **Настройки 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 вебхука |

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

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

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

Метод: POST

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

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

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

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

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

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

## См. также

- [Обработка ошибок API](/06-reference/01-api/api-errors)
- [Базовые URL](/06-reference/01-api/api-base-urls)
- [Отправка через Omni API](/03-multiapi/02-api/mapi-102-omni-api-send)

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

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