Краткий ответ
Чтобы получать отчёты о доставке (DLR) через webhook, поднимите HTTPS-endpoint, который принимает POST-запросы, и зарегистрируйте его URL у провайдера сообщений. Сохраняйте каждое событие, быстро отвечайте статусом 2xx и обрабатывайте событие асинхронно. Сопоставляйте события с вашими записями по ID сообщения, убирайте дубликаты и не позволяйте позднему статусу перезаписать финальный.
Настройте endpoint
Во время разработки туннель даёт локальному серверу публичный HTTPS-адрес.
- Поднимите HTTPS-endpoint, который принимает POST-запросы с телом в формате JSON.
- Передайте URL провайдеру, чтобы он был настроен на нужный аккаунт или субаккаунт.
- Отправьте тестовое сообщение на свой номер и запишите в лог необработанное тело события.
- Сопоставляйте нужные поля по реальным событиям, а не по предполагаемым названиям полей.
- Сохраняйте примеры payload как тестовые фикстуры для каждого используемого канала.
Какие статусы вы получите?
Провайдеры преобразуют квитанции операторов и каналов в собственные названия статусов. Это нормализованный набор, который OmniChannels.ai использует в SMS, WhatsApp и других каналах.
| Статус | Значение | Финальный? |
|---|---|---|
| SUBMITTED | Принято и поставлено в очередь | Нет |
| SENT | Передано оператору или в канал | Нет |
| DELIVERED | Подтверждено на устройстве | Обычно да; может последовать READ |
| READ | Открыто, в каналах, которые передают статус прочтения | Да |
| FAILED | Не доставлено, с указанием причины, если она доступна | Да |
| REJECTED | Отклонено, например из-за незарегистрированного имени отправителя (Sender ID) | Да |
Сделайте обработчик надёжным
- Сохраните необработанное тело события, затем верните 2xx. Если сохранить не удалось, верните 5xx, чтобы событие отправили повторно.
- Выполняйте основную работу в очереди или воркере, а не до ответа.
- Убирайте дубликаты по ID сообщения: один и тот же статус может прийти дважды.
- Ранжируйте статусы, чтобы поздний SENT никогда не перезаписывал DELIVERED.
- Принимайте незнакомые значения статусов, а не завершайте обработку ошибкой.
- Никогда не отправляйте сообщение повторно изнутри обработчика webhook.
Защитите endpoint и восстановите пропущенные отчёты
Принимайте только HTTPS, используйте длинный неугадываемый путь, проверяйте структуру тела запроса и подтверждайте состояние запросом статуса перед необратимыми действиями, например возвратами. Если ваш endpoint был недоступен, попросите провайдера повторно отправить квитанции за этот период или считайте статусы через его эндпоинты отчётности.
По SMPP квитанции приходят как deliver_sm в рамках bind, а не через webhook. Некоторые операторы присылают квитанции с задержкой или не присылают вовсе, поэтому считайте их веским свидетельством, а не доказательством прочтения.