Webhooks

Webhooks: уведомления о событиях

Webhooks позволяют получать HTTP-уведомления на ваш сервер при наступлении событий: входящие сообщения, исходящие сообщения, изменения статусов и другие.

Как работает

1. Вы регистрируете URL вашего сервера через PATCH /v1/webhooks
2. WazzaBee отправляет тестовый запрос на ваш URL: если он не вернёт 200, регистрация будет отклонена
3. При наступлении событий WazzaBee отправляет POST-запрос на ваш URL с данными события
4. Каждый запрос подписан HMAC-SHA256, и вы можете проверить подлинность

Два способа подключить webhook

1. Через личный кабинет (просто, без программиста). Откройте «Коннекторы» → «API» → блок «Webhook для входящих». Вставьте адрес вашего сервера и нажмите «Подключить», и кабинет сам проверит адрес и покажет секретный ключ для подписи.

2. Через REST API (для автоматизации). Отправьте запрос PATCH /v1/webhooks, как описано ниже.

Вебхук настраивается один раз, поэтому запрос удобнее отправить со своего сервера. Если отправляете его из браузера и видите Failed to fetch, проверьте, что метод написан заглавными буквами (PATCH), а ваш адрес отвечает 200 на тестовый запрос не дольше 10 секунд.

PATCH /v1/webhooks: регистрация/обновление

URL

PATCH https://api.wazzabee.com/api-gateway/v1/webhooks

Заголовки

Authorization: Bearer ВАШ_API_КЛЮЧ

Content-Type: application/json

Параметры тела запроса

Доступные подписки (subscriptions)

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

curl -X PATCH "https://api.wazzabee.com/api-gateway/v1/webhooks" \

  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \

  -H "Content-Type: application/json" \

  -d '{

    "webhooksUri": "https://ваш-сервер.com/webhook/wazzabee",

    "subscriptions": [

      "messages_incoming",

      "messages_outgoing",

      "messages_status"

    ]

  }'

Успешный ответ (200 OK)

{

  "success": true,

  "webhooksUri": "https://ваш-сервер.com/webhook/wazzabee",

  "subscriptions": [

    "messages_incoming",

    "messages_outgoing",

    "messages_status"

  ],

  "secret": "a1b2c3d4e5f6...64-символьный-hex-ключ",

  "message": "Вебхук установлен. Сохраните secret, он используется для подписи уведомлений (HMAC-SHA256)."

}

Тестовый запрос

При регистрации вебхука WazzaBee сразу отправляет тестовый POST-запрос на ваш URL:

{

  "test": true,

  "event": "webhook_test",

  "challenge": "случайная_строка_для_подтверждения",

  "timestamp": "2026-03-12T10:00:00.000Z",

  "message": "WazzaBee webhook test: если вы видите это, ваш webhook работает корректно."

}

Ваш сервер должен ответить статусом 200. Если ответ не 200 или URL недоступен, регистрация вебхука будет отклонена с ошибкой.

Возможные ошибки при регистрации

GET /v1/webhooks: текущие настройки

URL

GET https://api.wazzabee.com/api-gateway/v1/webhooks

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

curl -X GET "https://api.wazzabee.com/api-gateway/v1/webhooks" \

  -H "Authorization: Bearer ВАШ_API_КЛЮЧ"

Ответ: вебхук настроен (200 OK)

{

  "success": true,

  "webhook": {

    "webhooksUri": "https://ваш-сервер.com/webhook/wazzabee",

    "subscriptions": ["messages_incoming", "messages_outgoing"],

    "status": "active",

    "failureCount": 0,

    "createdAt": "2026-03-12T08:00:00.000Z",

    "updatedAt": "2026-03-12T08:00:00.000Z"

  }

}

Ответ: вебхук не настроен (200 OK)

{

  "success": true,

  "webhook": null,

  "message": "Вебхук не настроен"

}

Описание полей

Повторная отправка

Если ваш сервер не ответил кодом 2xx за 10 секунд (вернул ошибку, недоступен или не успел ответить), WazzaBee отправит то же уведомление повторно. Паузы между попытками растут: 1 минута, 5 минут, 15 минут, 1 час, 3 часа, 6 часов, 12 часов. Всего 8 попыток примерно за сутки.

Заголовки каждой отправки

Повтор может прийти позже следующих уведомлений. Порядок сообщений восстанавливайте по полю timestamp.

Когда вебхук отключается

Уведомление считается недоставленным, если не прошла ни одна из 8 попыток. После 10 недоставленных уведомлений подряд вебхук переходит в статус disabled. Любая успешная доставка обнуляет счётчик. Все попытки видны в журнале доставки в кабинете: «Коннекторы» → «API».

Статусы доставки (messages_status)

По каждому исходящему сообщению с линии официального WhatsApp (WABA) приходит уведомление о смене статуса. queueId совпадает с queueId из ответа POST /v1/messages/send, по нему сопоставляйте статус со своей отправкой. Если при отправке был передан campaignId, он тоже приходит.

{
  "statuses": [{
    "messageId": "uuid",
    "queueId": "uuid",
    "campaignId": "promo_oct",
    "channelId": "uuid",
    "chatId": "77071234567",
    "conversationId": "uuid",
    "contactId": "uuid",
    "status": "delivered",
    "error": null,
    "timestamp": "2026-09-30T12:00:00.000Z"
  }]
}

Те же данные можно запросить в GET /v1/messages: поля status, sentAt, deliveredAt, readAt, error.

Нажатия кнопок (messages_button)

Когда абонент нажимает кнопку шаблона, кроме обычного входящего приходит отдельное событие. В replyTo уже указано, на какое исходящее ответили: queueId, campaignId (ваша метка из отправки через API) и broadcastId (если шаблон ушёл рассылкой из кабинета). Искать исходное сообщение по context самому не нужно.

{
  "buttons": [{
    "messageId": "uuid",
    "channelId": "uuid",
    "chatId": "77071234567",
    "contactId": "uuid",
    "conversationId": "uuid",
    "button": { "type": "button", "id": null, "title": "Да, интересно", "payload": "YES_INTERESTED" },
    "replyTo": {
      "messageId": "uuid",
      "queueId": "uuid",
      "campaignId": "promo_oct",
      "broadcastId": null
    },
    "timestamp": "2026-09-30T12:00:00.000Z"
  }]
}

replyTo равен null, если исходное сообщение не найдено (например, отправлено не через WazzaBee).

Свои заголовки и параметры в адресе

Если ваш сервер принимает уведомления только с авторизацией, передайте заголовки в поле headers при регистрации вебхука. Они уходят с каждым уведомлением, с повторами и с тестовым запросом. Статические данные (например, идентификатор вашей системы) можно добавить прямо в адрес: https://ваш-сервер.com/hook?source=wazzabee&system=crm. Заголовки можно задать и в кабинете: «Коннекторы» → «API» → блок вебхука.

{
  "webhooksUri": "https://ваш-сервер.com/hook?source=wazzabee",
  "subscriptions": ["messages_incoming", "messages_status", "messages_button"],
  "headers": { "Authorization": "Bearer ваш-токен" }
}

Проверка подписи (HMAC-SHA256)

Каждое уведомление подписано с помощью secret, полученного при регистрации вебхука. Рекомендуем всегда проверять подпись для защиты от поддельных запросов.

Пример проверки на Node.js

const crypto = require("crypto");



function verifyWebhookSignature(body, signature, secret) {

  const expected = crypto

    .createHmac("sha256", secret)

    .update(JSON.stringify(body))

    .digest("hex");

  return signature === expected;

}



// В обработчике webhook:

app.post("/webhook/wazzabee", (req, res) => {

  const signature = req.headers["x-webhook-signature"];

  if (!verifyWebhookSignature(req.body, signature, YOUR_WEBHOOK_SECRET)) {

    return res.status(401).send("Invalid signature");

  }

  // Обработка события...

  res.status(200).send("OK");

});

Пример проверки на Python

import hmac

import hashlib

import json



def verify_signature(body: dict, signature: str, secret: str) -> bool:

    expected = hmac.new(

        secret.encode(),

        json.dumps(body).encode(),

        hashlib.sha256

    ).hexdigest()

    return hmac.compare_digest(signature, expected)



# В обработчике Flask:

@app.route("/webhook/wazzabee", methods=["POST"])

def handle_webhook():

    signature = request.headers.get("X-Webhook-Signature", "")

    if not verify_signature(request.json, signature, YOUR_WEBHOOK_SECRET):

        return "Invalid signature", 401

    # Обработка события...

    return "OK", 200

Формат входящего webhook-уведомления

При поступлении входящего сообщения WazzaBee отправляет POST-запрос на ваш URL со следующей структурой:

{
  "channel_id": "uuid",
  "channel_type": "whatsapp_waba",
  "channel_name": "WhatsApp Business",
  "conversation_id": "uuid",
  "message": {
    "id": "msg_id",
    "from": "77771234567",
    "sender_name": "Клиент",
    "type": "text",
    "text": "Здравствуйте!",
    "timestamp": "1712345678"
  },
  "operator": {
    "crm_user_id": "manager-42",
    "crm_user_name": "Алексей Менеджер"
  },
  "ad": {
    "ad_id": "120255518599590051",
    "source_type": "ad",
    "headline": "Visa4U",
    "text": "Отказали в визе? Не все потеряно!",
    "media_type": "video",
    "image_url": "https://scontent.xx.fbcdn.net/...jpg",
    "video_url": "https://video.xx.fbcdn.net/...mp4",
    "url": "https://fb.me/2abcXYZ",
    "click_id": "AfgHqhgPqgcChoXjlCqLkHfWKeS8"
  },
  "raw": { ... }
}

Описание полей

Блок ad: источник обращения

Если клиент нажал «Написать в WhatsApp» в рекламе Instagram или Facebook, вместе с уведомлением приходит блок ad. У обычных обращений его нет: проверяйте наличие самого поля, а не значения внутри. Блок приходит только на линиях официального WhatsApp: такие данные Meta передаёт лишь по WABA.

Ответы клиентов на кнопки WABA-шаблонов

Когда вы отправляете клиенту одобренный WABA-шаблон с кнопками Quick Reply (или Interactive buttons / list), и клиент нажимает кнопку, WazzaBee присылает в webhook дополнительные поля message.interactive и message.context. Поле message.text содержит реальный текст нажатой кнопки, его можно показывать в чате CRM как обычное сообщение клиента.

Значения message.type

Структура поля message.interactive

{

  "type": "button" | "button_reply" | "list_reply",

  "id":    "идентификатор кнопки" | null,

  "title": "текст кнопки, который видел клиент" | null,

  "description": "описание (только для list_reply)" | null,

  "payload": "значение payload (только для type=button)" | null

}

Структура поля message.context

Ссылка на исходное HSM-сообщение, на кнопку которого нажал клиент:

{

  "id":          "uuid исходящего сообщения в WazzaBee",

  "from":        "номер отправителя (ваш WABA-номер)",

  "gs_id":       "внутренний ID сообщения у провайдера",

  "meta_msg_id": "wamid.HBgL... (ID в Meta)"

}

Пример webhook: клиент нажал кнопку «Да, буду вовремя»

{

  "channel_id": "f0e8...",

  "channel_type": "whatsapp_waba",

  "channel_name": "WhatsApp Business",

  "conversation_id": "b1c2...",

  "message": {

    "id": "wamid.HBgLNzcwMTEwMDEwNTkVAgASGBQzQTY5NkJCNjE3M0JGQjE1MjVEMQA=",

    "from": "77011001059",

    "sender_name": "Фархат",

    "type": "button",

    "text": "Да, буду вовремя",

    "interactive": {

      "type": "button",

      "title": "Да, буду вовремя",

      "payload": "Да, буду вовремя"

    },

    "context": {

      "id": "584abab5-911a-49ca-a750-95e8116be1e1",

      "from": "77079119977",

      "gs_id": "378ba4ed-5a5d-4c58-a4e8-b6ca08b2ad7a",

      "meta_msg_id": "wamid.HBgL..."

    },

    "timestamp": "1776870877"

  },

  "operator": null,

  "raw": { ... }

}

Пример: клик по Interactive list (Meta Cloud API v3)

{

  "message": {

    "type": "interactive",

    "text": "Доставка на дом",

    "interactive": {

      "type": "list_reply",

      "id": "delivery_home",

      "title": "Доставка на дом",

      "description": "По адресу клиента"

    },

    "context": { "meta_msg_id": "wamid.HBgL..." }

  }

}

Исходящие WABA-шаблоны (messages_outgoing)

Когда вы отправляете HSM-шаблон через API или из UI WazzaBee, при подписке на messages_outgoing в webhook приходит структура с полем template (если шаблон содержит кнопки):

{

  "messages": [{

    "messageId": "uuid",

    "direction": "outgoing",

    "type": "template",

    "text": "Здравствуйте! Подтвердите встречу завтра в 15:00.",

    "template": {

      "name": "appointment_reminder_v2",

      "language": "ru",

      "buttons": [

        { "type": "quick_reply", "text": "Да, буду вовремя" },

        { "type": "quick_reply", "text": "Перенести" }

      ]

    },

    "timestamp": "2026-04-22T15:14:42Z"

  }]

}

Это позволяет вашей CRM отрисовать кнопки в ленте чата точно так же, как они выглядят у клиента в WhatsApp.

Кто отправил исходящее сообщение (author)

Событие messages_outgoing приходит на любой ответ клиенту: написанный оператором в кабинете WazzaBee, отправленный из чата, встроенного в вашу CRM, посланный шаблоном или через POST /v1/messages/send. Вместе с сообщением приходит блок author: кто именно ответил.

{
  "messages": [{
    "messageId": "uuid",
    "channelId": "uuid",
    "chatId": "77001234567",
    "contactId": "uuid",
    "conversationId": "uuid",
    "direction": "outgoing",
    "type": "text",
    "text": "Здравствуйте! Ваши документы готовы.",
    "author": {
      "kind": "operator",
      "name": "Назерке А.",
      "userId": "manager-42"
    },
    "timestamp": "2026-07-30T09:20:12.000Z"
  }]
}

Поля блока author