---
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 вебхука в запросе. Платформа будет отправлять POST-запросы на этот URL.

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

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

## Что это

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

## Где указать

В запросе через умный шлюз — в поле **webhook**.

Если не указать — используется URL из настроек имени отправителя или API-ключа.

## Что приходит

### Статус сообщения

Событие: **messageStatus**

Поля:

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

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

| Статус | Что означает |
|---|---|
| sent | Отправлено |
| delivered | Доставлено |
| seen | Просмотрено |
| failed | Ошибка |
| undeliverable | Не удалось доставить |
| unknown | Неизвестно |

## Как обрабатывать

1. **Принимайте POST-запросы** на ваш URL.
2. **Отвечайте 200 OK** быстро.
3. **Обрабатывайте асинхронно** — не блокируйте ответ.
4. **Логируйте всё** — для диагностики.
5. **Используйте messageId** как ключ.

## Пример логики

1. Вы отправили запрос с webhook = https://myapp.com/otp-status.
2. Платформа отправила сообщение.
3. Когда статус изменился — платформа отправила POST на ваш URL.
4. Ваш сервер получил статус delivered.
5. Обновили статус в базе.

## Приоритет вебхуков

Вебхук определяется в следующем порядке:

1. Поле webhook в запросе (наивысший приоритет).
2. Настройки имени отправителя.
3. Настройки API-ключа.

Если в запросе указан webhook — он используется. Если нет — берётся из настроек отправителя.

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

1. **HTTPS обязателен.**
2. **Проверяйте источник** — можно ограничить по IP.
3. **Валидируйте данные.**
4. **Не возвращайте чувствительные данные.**

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

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

## Что дальше

- [Обработка ошибок умного шлюза](/02-otp/02-smart-gateway/otp-206-errors)
- [Правила доставки](/02-otp/02-smart-gateway/otp-204-delivery-rules)

## См. также

- [Вебхуки в API](/06-reference/01-api/api-webhooks)
- [Первый запрос через умный шлюз](/02-otp/02-smart-gateway/otp-202-first-request)
- [Настройка каскада](/02-otp/02-smart-gateway/otp-203-cascade-rules)

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

- OTP-коды: support@otpcod.ru