Вебхуки позволяют узнавать о событиях, которые происходят на стороне Wazzup. Например, что у сообщения изменился статус на «Доставлено» или канал «Не авторизован», а значит, канал надо переподключить.

Wazzup отправляет вебхуки на ваш HTTP‑endpoint. Нужно подписываться на вебхуки по конкретному дочернему аккаунту с использованием client_access_token в заголовке: Authorization: Bearer <client_access_token>

Поддерживаемые события

• message.add — получено входящее сообщение от клиента;
• message.status_update — обновился статус исходящего сообщения. Например, с «Доставлено» на «Прочитано»;
• message.delete — сообщение удалено;
• message.edit — сообщение отредактировано. Приходит только по сообщениям на каналах, которые поддерживают редактирование;
• waba_template.status_update — изменился статус модерации шаблона WABA. Статус модерации показывает, можно ли использовать шаблон;
• channel.status_update — изменился статус канала;
• channel.create — канал создан;
• channel.delete — канал удалён;
• channel.qr_update — обновился QR, код подключения → необходимо отобразить новый код клиенту. Приходит для WhatsApp, Telegram Personal, Viber;
• channel.waba_tier_update — изменился уровень (tier) WABA. Уровень показывает, сколько переписок можно начинать первым в течение 24 часов;
• group_chat.memberships_update — изменился состав группового чата WhatsApp или участник чата переименован;
• group_chat.update — изменилась информация о групповом чате.

Управление подписками

Подписаться на вебхуки

В рамках одного вызова можно подписаться сразу на несколько событий.

Метод POST /v2/webhooks

Пример запроса:

curl -L 'https://tech.wazzup24.com/v2/webhooks'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <client_access_token>'
-d '{
"data": [
{
"url": "https://webhook.site/73796fab-2e6d-492a-b68e-061d825b7db5",
"event": "message.add"
},
{
"url": "https://webhook.site/73796fab-2e6d-492a-b68e-061d825b7db5",
"event": "message.status_update"
}
]
}'

Пример ответа:

{
"data": [
{
"id": "d6c04-7623-43ae-a024-7b36c4004c13",
"url": "https://webhook.site/73796fab-2e6d-492a-b68e-061d825b7db5",
"event": "message.add"
},
{
"id": "b0a26-10d9-4d47-8cda-892c9b471a05",
"url": "https://webhook.site/73796fab-2e6d-492a-b68e-061d825b7db5",
"event": "message.status_update"
}
],
"meta": {
"timestamp": 1759494767
}
}

Результат: Создана подписка на события message.add и message.status_update. Вебхуки будут приходить на адрес https://webhook.site/73796fab-2e6d-492a-b68e-061d825b7db5.

В ответе содержится id подписки — ID нужно для управления вебхуками в других методах.

Изменение подписки на вебхуки

Метод позволяет подписаться на другие вебхуки, отменить подписку или изменить url для получения событий.

Метод PATCH /v2/webhooks

Пример:

curl -L -X PATCH 'https://tech.wazzup24.com/v2/webhooks'
-H 'Authorization: Bearer <client_access_token>'
-H 'Content-Type: application/json' -d '{
"data": [
{
"id": "42cdd-a0a6-40fd-b55b-040e7c605d0a",
"url": "https://webhook.site/1d2c6a79-d709-4d00-ad24-856e3d8edfd5",
"event": "message.delete"
}
]
}'

Пример ответа:

{
"data": [
{
"id": "d6c04-7623-43ae-a024-7b36c4004c13",
"url": "https://webhook.site/new-webhook-url",
"event": "message.delete"
}
],
"meta": {
"timestamp": 1759483585
}
}

Результат: Для подписки с id: 411d6c04-7623-43ae-a024-7b36c4004c13 обновлен url для получения вебхуков.

Получить список подписок на вебхуки

Метод GET /v2/webhooks

Пример:

curl -L 'https://tech.wazzup24.com/v2/webhooks' -H 'Authorization: Bearer <client_access_token>'

Пример ответа:

{
"data": [
{
"id": "891cdbf4-07bd-4c24-942b-27d5c820c879",
"url": "https://webhook.site/3d76c4a6-f1ab-4090-a766-3f9a07bca714",
"event": "channel.status_update"
},
{
"id": "1e35de57-ca04-45ba-a345-67f0d8b11138",
"url": "https://webhook.site/3d76c4a6-f1ab-4090-a766-3f9a07bca714",
"event": "channel.create"
},
{
"id": "ccbe0af3-2f12-4e6e-8c35-78fe3c9d3714",
"url": "https://webhook.site/3d76c4a6-f1ab-4090-a766-3f9a07bca714",
"event": "channel.update"
}
],
"meta": {
"timestamp": 1759483435
}
}

Результат: Список всех подписок на вебхуки для дочернего аккаунта.

Удалить подписку на вебхук

Метод DELETE /v2/webhooks

Пример:

curl -L -X DELETE 'https://tech.wazzup24.com/v2/webhooks'
-H 'Authorization: Bearer <client_access_token>'
-H 'Content-Type: application/json'
-d '{
"data": [
{
"id": "dbf4-07bd-4c24-942b-27d5c820c879"
}
]
}'

Пример ответа:

{
"data": null,
"meta": {
"timestamp": 1759483702
}
}

Результат: Подписка с id: dbf4-07bd-4c24-942b-27d5c820c879 удалена. Вы больше не получаете вебхуки с этим событием.

Структура вебхука

{
"event": "message.add" | "message.status_update" | "message.delete" | "message.edit" | "channel.status_update" | "channel.delete" | "channel.create" | "channel.qr_update" | "channel.waba_tier_update" | "waba_template.status_update" | "group_chat.memberships_update" | "group_chat.update",
"data": [],
"meta": {
"idempotency_key": UUIDv4,
"timestamp": Unix timestamp в секундах
}
}

Внутри поля data содержится само событие. Структура событий:

message.add

{
"message_id": "a14325c0-97c0-43dd-917e-f0ad7460b6a9",
"channel_id": "a14325c0-97c0-43dd-917e-f0ad7460b6a9",
"direction": "inbound",
"quoted_message_id": "90126ace-fc10-44ed-90de-c30c3802fcf5" | null,
"timestamp": 1762340622177,
"crm_user_id": "123" | null,
"status": "sent",
"recipient": {
"chat_id": "7999999999",
"username": "my_tg_user",
"phone": "79851112233",
"chat_type": "telegram",
"name": "Tg User"
},
"text": "Привет!",
"attachment": {
"url": "https://some.url/photo.jpg",
"name": "photo.jpg",
"mimetype": "image/jpeg",
"size": 14832,
"sha1": "123456abcdf"
},
"template": {
"id": "2b1c3d4e-5f67-890a-bcde-f123456789ab",
"values": [ "Привет" ],
"buttons": [
{ "text": "Да", "payload": "yes" },
{ "text": "Нет", "payload": "no" }
]
}
}

message.status_update

{
"message_id": UUIDv4 | null,
"request_id": UUIDv4 | null,
"status": "accepted" | "sent" | "delivered" | "read" | "failed",
"reason": string | null
}

Возможные значения reason в зависимости от status.

При status: "accepted" | "sent" | "delivered" | "read" — reason всегда null

При status: "failed" — reason показывает причину ошибки.

message.delete

{
"message_id": UUIDv4,
"crm_user_id": string | null,
"timestamp": Unix timestamp в миллисекундах
}

message.edit

{
"message_id": UUIDv4,
"crm_user_id": string | null,
"timestamp": Unix timestamp в миллисекундах
"text": string, // опционально
"old_text": string, // опционально
"attachment": {},
"old_attachment": {}
}

waba_template.status_update

{
"template_id": UUIDv4,
"status": "APPROVED" | "PENDING" | "REJECTED" | "PAUSED" | "DISABLED",
"timestamp": unix epoch,
}

channel.status_update

{
"channel_id": UUIDv4,
"status": "active" | "disabled" | "init",
"reason": string | null
}

Возможные значения reason в зависимости от status:

• При status: "active" — reason всегда null
• При status: "init" — reason: wait_for_password, wait_for_code, qr, sync или null
• При status: "disabled" — reason: blocked, not_enough_money, rejected, unauthorized, foreignphone, qridle, openelsewhere или null

channel.delete

{
"channel_id": UUIDv4,
"timestamp": Unix timestamp в миллисекундах,
}

channel.create

{
"channel_id": UUIDv4,
"timestamp": Unix timestamp в миллисекундах,
}

channel.qr_update

{
"channel_id": UUIDv4,
"qr_code": string,
"platform": 'whatsapp' | 'telegram_api' | 'viber'
}

channel.waba_tier_update

Meta* присваивает аккаунтам WhatsApp Business уровни tier — они показывают, сколько 24-часовых переписок можно начать сутки.

{
"channel_id": UUIDv4,
"tier": "TIER_0" | "TIER_1K" | "TIER_10K" | "TIER_100K" | "TIER_UNLIMITED",
}

Возможные значения:

• TIER_0: 250 переписок,
• TIER_1K: 1000 переписок,
• TIER_10K: 10 000 переписок,
• TIER_100K: 100 000 переписок,
• TIER_UNLIMITED: без ограничений.

group_chat.memberships_update

{
"meta": {
"idempotency_key": "945ff8a4-bb3c-45f7-8d1a-b40f7ce2fb",
"timestamp": 1760690824
},
"data": [
{
"group_id": "3c67afca-6cbf-4517-b120-c4a83dbd41",
"members": [
{
"group_member_id": "c705786d-bba5-43f9-9b-5f6f5d4ba623",
"name": "Маша",
"avatar_url": null,
"status": "in_group" | "invited" | "unknown" | "deleted" | "not_exists" |
}
]
}
],
"event": "group_chat.memberships_update"
}

Рекомендации по надёжности

• Отвечайте быстро 200 OK, остальную обработку делайте асинхронно.
• Ретраи. При временных ошибках доставки мы можем повторить отправку (количество попыток и интервалы могут меняться). Делайте обработку идемпотентной.
• Защита. Размещайте endpoint за HTTPS.
• Лимиты. Не выполняйте тяжёлую работу синхронно в обработчике вебхука — используйте очередь/фоновую обработку.

Быстрый чек‑лист

1. Разверните публичный POST‑endpoint (HTTPS), принимайте application/json.
2. Храните логи: статус ответа, тело, заголовки.
3. Подпишитесь на события message.add и message.status_update — это минимум, чтобы понимать что сообщение отправлено и доставлено.
4. Проверьте сценарии: входящее сообщение → ваш сервис → ответ 200; исходящее сообщение → статус‑вебхуки.

*Запрещены и признаны экстремистскими на территории РФ