Определение
Вебхук — это HTTP-запрос, который платформа отправляет на указанный вами URL при каждом событии: сообщение доставлено, прочитано или не доставлено, пришёл ответ клиента. Ваша система узнаёт о событии сразу, без опроса (polling).
Вы регистрируете endpoint (например, https://example.com/hooks/messaging). Когда происходит событие, платформа отправляет POST-запрос с телом в формате JSON. В нём указаны ID сообщения, статус, время события, канал и сведения об ошибке. Ваш сервер должен быстро ответить кодом 2xx и обработать событие асинхронно.
Проектируйте обработчик с учётом реальных условий доставки: вебхуки могут приходить с задержкой, в другом порядке или повторно. Используйте ID сообщения и статус для дедупликации, не переводите статус назад (например, из READ в DELIVERED) и делайте обработчик идемпотентным, безопасным для повторных запросов.
Безопасность: принимайте только HTTPS, проверяйте подпись или общий секрет в каждом запросе и не доверяйте данным, пока проверка не пройдена. Общепринятые подходы к подписи и повторным отправкам описаны, например, в спецификации Standard Webhooks.
В сфере сообщений вебхуки передают данные для отчётов о доставке, показателей прочтения, входящих ответов, отписок (opt-out) и решений о переключении на резервный канал (fallback).
OmniChannels.ai отправляет вебхуки со статусами доставки (SUBMITTED, SENT, DELIVERED, READ, FAILED, REJECTED), приведёнными к единому формату для всех каналов.
Пример
{"messageId":"msg_123","channel":"whatsapp","status":"DELIVERED","timestamp":"2026-10-10T09:15:02Z"}