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

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)

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

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

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

FAQ

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

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

• Техническая документация и основы работы SMS API: полное руководство
• Интеграция SMS API с популярными языками программирования: пошаговое руководство
• Автоматизация бизнес‑процессов через SMS API: как использовать триггерные сообщения и уведомления
• Масштабирование и оптимизация доставки SMS: практические рекомендации 2026
• Полное руководство по SMS API: от выбора провайдера до интеграции
• Методы передачи данных: REST, SOAP и JSON в SMS API
• Авторизация и безопасность в SMS‑API: ключи, OAuth и токены
• Обработка ответов сервера и коды ошибок SMS шлюза: справочник для разработчиков