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 — описано ниже.

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": "Вебхук не настроен"
}

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

Проверка подписи (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