# Практическое руководство по работе с Webhooks для отслеживания статусов доставки SMS

- Опубликовано: 2026-05-20T11:18:19+00:00
- Обновлено: 2026-05-20T11:18:19+00:00
- Автор: Алла Богатырёва
- Канонический URL: https://smsblog.ru/sms-rassylki/prakticheskoe-rukovodstvo-po-rabote-s-webhooks-dlya-otslezhivaniya-sta/

Webhooks позволяют получать мгновенные уведомления о статусах отправленных SMS. В 2026 году большинство провайдеров поддерживают JSON‑callback, что упрощает интеграцию и повышает надёжность доставок.

## Что такое Webhooks в контексте SMS‑маркетинга?

Webhooks — это HTTP‑callback, отправляемый провайдером, когда состояние сообщения меняется. Типы статусов: `sent`, `delivered`, `failed`, `undelivered`. Эти данные позволяют строить аналитические дашборды и автоматически обновлять CRM.

## Как настроить callback‑URL на стороне клиента

1. Зарегистрируйте endpoint, открытый для HTTPS. 2. Подтвердите подпись, если провайдер требует HMAC‑SHA256. 3. Добавьте в настройках аккаунта провайдера URL. 4. Тестируйте отправкой пробного сообщения.

```
POST /webhook
X-Signature: sha256=abcdef123456
Content-Type: application/json

{
  "messageId": "12345",
  "status": "delivered",
  "timestamp": "2026-05-20T14:32:00Z"
}
```

### Проверка подписи HMAC

Если провайдер отправляет `X-Signature`, вычислите HMAC от тела запроса и сравните. Это защищает от подделки.

```
import hmac, hashlib
signature = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
```

## Обработка статусов доставки в бизнес‑логике

Статусы `sent` и `delivered` обычно считаются успешными. `failed` и `undelivered` требуют повторной отправки или отклика пользователю.

- При `failed` проверьте код ошибки (например, `12004` – номер недоступен).
- В случае `undelivered` инициируйте альтернативный канал (WhatsApp, push).
- Обновите статус заказа в CRM и отправьте уведомление менеджеру.

## Интеграция Webhooks с CRM и аналитикой

Внедрите middleware, который сериализует webhook‑payload в формат, совместимый с вашим CRM. Пример использования RabbitMQ для асинхронной обработки.

```
def handle_webhook(event):
    data = json.loads(event.body)
    if data["status"] == "delivered":
        update_crm(order_id=data["messageId"], status="delivered")
        publish_to_queue(event.body)
```

## Проблемы и лучшие практики

- Проверка idempotency: храните уже обработанные `messageId`, чтобы избежать дублей.
- Установите таймаут 30 секунд, чтобы не блокировать провайдер.
- Используйте HTTPS с валидным сертификатом.
- Резервный endpoint: добавьте failover‑URL для высокой доступности.
- Логи: пишите подробные логи для аудита и диагностики.

## Сравнение популярных SMS‑провайдеров по поддержке Webhooks

| Провайдер | Формат payload | Подпись | Холодные вызовы |
| --- | --- | --- | --- |
| Provider A | JSON | HMAC‑SHA256 | Да |
| Provider B | XML | Нет | Нет |
| Provider C | JSON | OAuth2.0 | Да |

## FAQ

- **Как проверить, что webhook пришёл?** Проверяйте заголовок `X-Webhook-Id` и payload.
- **Можно ли использовать Webhooks для массовых рассылок?** Да, но убедитесь в масштабируемости сервера.
- **Что делать при потере webhook‑payload?** Настройте повторную отправку провайдером и храните резервные копии.
- **Как избежать дублирования статусов?** Храните индикатор `processed` в базе.
- **Поддерживают ли Webhooks только SMS‑провайдеры?** Многие мессенджеры также предлагают callback‑события.

## Дополнительные ресурсы

- [Техническая документация и основы работы SMS API: полное руководство](http://smsblog.ru/biznes-kommunikacii/tekhnicheskaya-dokumentatsiya-i-osnovy-raboty-sms-api-polnoe-rukovodst/)
- [Интеграция SMS API с популярными языками программирования: пошаговое руководство](http://smsblog.ru/tarify-i-ceny/integratsiya-sms-api-s-populyarnymi-yazykami-programmirovaniya-poshago/)
- [Автоматизация бизнес‑процессов через SMS API: как использовать триггерные сообщения и уведомления](http://smsblog.ru/biznes-kommunikacii/avtomatizatsiya-biznes-protsessov-cherez-sms-api-kak-ispolzovat-trigge/)
- [Масштабирование и оптимизация доставки SMS: практические рекомендации 2026](http://smsblog.ru/sms-rassylki/masshtabirovanie-i-optimizatsiya-dostavki-sms-prakticheskie-rekomendat/)
- [Полное руководство по SMS API: от выбора провайдера до интеграции](http://smsblog.ru/obzory-i-sravneniya/polnoe-rukovodstvo-po-sms-api-ot-vybora-provaydera-do-integratsii/)
- [Методы передачи данных: REST, SOAP и JSON в SMS API](http://smsblog.ru/mobilnyj-marketing/metody-peredachi-dannykh-rest-soap-i-json-v-sms-api/)
- [Авторизация и безопасность в SMS‑API: ключи, OAuth и токены](http://smsblog.ru/biznes-kommunikacii/avtorizatsiya-i-bezopasnost-v-sms-api-klyuchi-oauth-i-tokeny/)
- [Обработка ответов сервера и коды ошибок SMS шлюза: справочник для разработчиков](http://smsblog.ru/sms-rassylki/obrabotka-otvetov-servera-i-kody-oshibok-sms-shlyuza-spravochnik-dlya/)

## Источники

- В материале не указаны внешние источники.