Вебхуки Wazzup: сообщения WhatsApp, статусы и защита адреса

Вебхук Wazzup: подписка PATCH /v3/webhooks, проверочный запрос, настоящие события WhatsApp, правки и удаления, защита без подписи — Python, PHP, Node.js.

Опубликовано 22 минуты чтения

  • wazzup
  • whatsapp
  • вебхуки
  • api
  • localhost
  • туннель
Обложка: вебхук Wazzup — сообщения WhatsApp, правка с тем же messageId

Wazzup присылает события WhatsApp на ваш адрес запросом POST с JSON: входящие и исходящие сообщения, правки, удаления, статусы доставки. Подключается вебхук одним запросом PATCH /v3/webhooks, и в ту же секунду Wazzup проверяет адрес: шлёт {"test":true} и ждёт ответ 200.

Три особенности, которые ломают типовой обработчик:

  1. При подключении по ключу API у вебхуков Wazzup нет подписи. Ни секретного заголовка, ни HMAC — отличить Wazzup от постороннего запроса можно только по секрету, который вы сами положите в адрес.
  2. Правка и удаление приходят с тем же messageId. Обработчик, который выбрасывает «уже виденный messageId» как повтор, потеряет и правки, и удаления.
  3. dateTime округлено до минуты. Время события по нему известно с точностью до минуты; порядок внутри минуты даёт только счётчик в миллисекундах, и опираться на него не стоит.

Всё ниже проверено 17.10.2026 на живом аккаунте Wazzup с подключённым WhatsApp: подписка, отказ подписки, восемь типов событий, обработчики на Python, PHP и Node.js.

Что понадобится

  • Аккаунт Wazzup с подключённым каналом WhatsApp и ключ API из кабинета Wazzup.
  • Публичный HTTPS-адрес для вебхука. Для отладки — адрес приёма на hook.csap.ru и туннель до вашего компьютера; на бесплатном тарифе — один адрес, одна сессия туннеля и 500 запросов в месяц.
  • Python 3, PHP 7.4+ или Node.js 18+ — обработчик дан на всех трёх, без сторонних библиотек.

Шаг 1. Канал WhatsApp и текущие настройки вебхуков

Ключ передаётся заголовком Authorization: Bearer <ключ>. Сначала узнайте channelId — он нужен, чтобы отвечать:

bash
export WAZZUP_API_KEY='ключ API'
curl -s https://api.wazzup24.com/v3/channels -H "Authorization: Bearer $WAZZUP_API_KEY"
json
[{"channelId":"0b1c2d3e-0000-4000-8000-000000000001","transport":"whatsapp","state":"active","plainId":"79000000002","name":"79000000002"}]

Текущие настройки вебхуков — GET /v3/webhooks. У нового аккаунта адреса нет, все подписки выключены:

json
{"webhooksUri":null,"subscriptions":{"messagesAndStatuses":false,"contactsAndDealsCreation":false,"channelsUpdates":false,"wabaTemplatesStatus":false}}

Шаг 2. Защита без подписи: секрет в адресе

Раз подписи нет, секрет кладётся в сам адрес вебхука — параметром:

код
https://hook.csap.ru/t/<токен>?key=<секрет>

Wazzup сохраняет адрес целиком и присылает события на него вместе с параметром: в запросе видно POST /?key=<секрет>. Обработчик сверяет key и отвечает 403 на всё остальное. Секрет — длинная случайная строка. Сгенерируйте его один раз и сохраните в файл: обработчик, проверка из шага 4 и подписка из шага 5 должны видеть одно значение, а $(openssl rand -hex 32) в новом терминале даст другое.

bash
openssl rand -hex 32 > .wazzup_secret   # один раз
export WAZZUP_WEBHOOK_SECRET=$(cat .wazzup_secret)   # в каждом терминале

Секрет в адресе виден всем, кто видит адрес: журналам веб-сервера (php -S пишет строку запроса вместе с ?key= в свой журнал), прокси, строкам туннеля и ленте hook.csap.ru, сотрудникам с доступом к настройкам Wazzup. Не пересылайте такие журналы и меняйте секрет при подозрении на утечку — новым PATCH.

Шаг 3. Обработчик вебхука: Python, PHP, Node.js

Что обработчик делает на любом языке:

  • Сверяет key за постоянное время (hmac.compare_digest, hash_equals, timingSafeEqual), а не через ==: обычное сравнение останавливается на первом несовпавшем символе, и по скорости ответа секрет можно подбирать по одному символу. Чужой или пустой — 403.
  • Отвечает 400 на битое тело и на JSON, который не объект — в ленте сразу видно, что виноват запрос, а не обработчик.
  • Сначала сохраняет тело, потом отвечает 200, в том числе на проверочный {"test":true}: каждое принятое тело дописывается строкой в wazzup-inbox.jsonl. Повтора после ошибки может не быть, поэтому тело должно остаться у вас, даже если разбор упадёт. Python и Node.js разбирают уже после ответа, PHP — до него.
  • Хранит сообщения по messageId. Новое — обрабатывает один раз; правку (isEdited) и удаление (isDeleted) — как изменение уже известного сообщения, а не как повтор.
  • Пропускает эхо (isEcho: true) — это исходящие сообщения, в том числе ответ самого бота. Без этой проверки бот начнёт отвечать сам себе.
  • Записывает статусы из массива statuses в сохранённое сообщение и сообщает об отключении канала (channelsUpdates).

Python

bot.py, только стандартная библиотека:

python
import hmac
import json
import logging
import os
import threading
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import parse_qs, urlparse

API_KEY = os.environ["WAZZUP_API_KEY"]
# Секрет из параметра key в webhooksUri: подписи у Wazzup нет.
SECRET = os.environ["WAZZUP_WEBHOOK_SECRET"]
# Сюда пишется каждое тело до ответа 200: повтора после ошибки может не быть.
INBOX = os.environ.get("WAZZUP_INBOX", "wazzup-inbox.jsonl")

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s")
log = logging.getLogger("wazzup")

messages = {}  # messageId → последнее известное состояние сообщения
lock = threading.Lock()


def send_text(channel_id: str, chat_id: str, text: str) -> None:
    req = urllib.request.Request(
        "https://api.wazzup24.com/v3/message",
        data=json.dumps({"channelId": channel_id, "chatType": "whatsapp",
                         "chatId": chat_id, "text": text}).encode(),
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=10) as resp:
        resp.read()


def on_message(m: dict) -> None:
    mid = m["messageId"]
    with lock:
        known = mid in messages
        messages[mid] = {**messages.get(mid, {}), **m}
    if m.get("isDeleted"):
        log.info("удалено %s", mid)
    elif m.get("isEdited"):
        log.info("исправлено %s", mid)
    elif known:
        log.info("повтор %s, пропускаю", mid)
    elif m.get("isEcho"):
        log.info("исходящее %s от %s", mid, m.get("authorName"))
    else:
        log.info("входящее %s %s", m["type"], mid)
        send_text(m["channelId"], m["chatId"], "Получил: " + (m.get("text") or m["type"]))


def handle(update: dict) -> None:
    try:
        for m in update.get("messages", []):
            on_message(m)
        for s in update.get("statuses", []):
            with lock:
                messages.setdefault(s["messageId"], {})["status"] = s["status"]
            log.info("статус %s → %s", s["messageId"], s["status"])
        for c in update.get("channelsUpdates", []):
            log.warning("канал %s → %s", c["channelId"], c["state"])
    except Exception as e:
        log.error("%s", e)


class Webhook(BaseHTTPRequestHandler):
    def do_POST(self):
        key = parse_qs(urlparse(self.path).query).get("key", [""])[0]
        if not hmac.compare_digest(key.encode(), SECRET.encode()):
            self.send_response(403)
            self.end_headers()
            return
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        try:
            update = json.loads(raw)
        except ValueError:
            update = None
        if not isinstance(update, dict):
            self.send_response(400)
            self.end_headers()
            return
        with lock, open(INBOX, "ab") as f:
            f.write(raw.replace(b"\n", b" ") + b"\n")
        # 200 — после записи тела, и на проверочный {"test": true} тоже.
        self.send_response(200)
        self.end_headers()
        if not update.get("test"):
            threading.Thread(target=handle, args=(update,), daemon=True).start()

    def log_message(self, fmt, *args):
        pass


ThreadingHTTPServer(("127.0.0.1", 8080), Webhook).serve_forever()

PHP

bot.php. Запросы PHP не делят память, поэтому сообщения лежат в SQLite — в рабочем боте это ваша база с тем же первичным ключом messageId:

php
<?php
// Запуск для отладки: php -S 127.0.0.1:8080 bot.php
$apiKey = getenv('WAZZUP_API_KEY');
$secret = getenv('WAZZUP_WEBHOOK_SECRET'); // параметр key в webhooksUri: подписи у Wazzup нет
$inbox = getenv('WAZZUP_INBOX') ?: __DIR__ . '/wazzup-inbox.jsonl';

if (!is_string($secret) || $secret === '') {
    http_response_code(500); // секрет не задан — ошибка настройки, а не запроса
    exit;
}
$key = $_GET['key'] ?? '';
if ($_SERVER['REQUEST_METHOD'] !== 'POST' || !is_string($key) || !hash_equals($secret, $key)) {
    http_response_code(403);
    exit;
}

$raw = file_get_contents('php://input');
$update = json_decode($raw, true);
if (!is_array($update)) {
    http_response_code(400);
    exit;
}
// Тело — в файл до разбора: повтора после ошибки может не быть.
file_put_contents($inbox, str_replace("\n", ' ', $raw) . "\n", FILE_APPEND | LOCK_EX);
if (!empty($update['test'])) {
    http_response_code(200); // проверочный запрос при подписке
    exit;
}

// Сообщения храним по messageId: правка и удаление приходят с тем же id.
$db = new PDO('sqlite:' . __DIR__ . '/wazzup.sqlite');
$db->exec('CREATE TABLE IF NOT EXISTS message (id TEXT PRIMARY KEY, body TEXT NOT NULL, status TEXT)');

function send_text(string $apiKey, string $channelId, string $chatId, string $text): void
{
    $ch = curl_init('https://api.wazzup24.com/v3/message');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey, 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode(
            ['channelId' => $channelId, 'chatType' => 'whatsapp', 'chatId' => $chatId, 'text' => $text],
            JSON_UNESCAPED_UNICODE
        ),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    if ($body === false || $code !== 201) {
        error_log("send_text: HTTP $code");
    }
}

foreach ($update['messages'] ?? [] as $m) {
    $ins = $db->prepare('INSERT OR IGNORE INTO message (id, body) VALUES (?, ?)');
    $ins->execute([$m['messageId'], json_encode($m, JSON_UNESCAPED_UNICODE)]);
    $isNew = $ins->rowCount() === 1;
    if (!$isNew) {
        $db->prepare('UPDATE message SET body = ? WHERE id = ?')
            ->execute([json_encode($m, JSON_UNESCAPED_UNICODE), $m['messageId']]);
    }

    if (!empty($m['isDeleted'])) {
        error_log('удалено ' . $m['messageId']);
    } elseif (!empty($m['isEdited'])) {
        error_log('исправлено ' . $m['messageId']);
    } elseif (!$isNew) {
        error_log('повтор ' . $m['messageId'] . ', пропускаю');
    } elseif (!empty($m['isEcho'])) {
        error_log('исходящее ' . $m['messageId'] . ' от ' . ($m['authorName'] ?? ''));
    } else {
        error_log('входящее ' . $m['type'] . ' ' . $m['messageId']);
        send_text($apiKey, $m['channelId'], $m['chatId'], 'Получил: ' . ($m['text'] ?? $m['type']));
    }
}

foreach ($update['statuses'] ?? [] as $s) {
    $db->prepare('UPDATE message SET status = ? WHERE id = ?')->execute([$s['status'], $s['messageId']]);
    error_log('статус ' . $s['messageId'] . ' → ' . $s['status']);
}

foreach ($update['channelsUpdates'] ?? [] as $c) {
    error_log('канал ' . $c['channelId'] . ' → ' . $c['state']);
}

http_response_code(200);

Node.js

bot.mjs, без зависимостей:

javascript
import http from "node:http";
import { appendFileSync } from "node:fs";
import { timingSafeEqual } from "node:crypto";

const API_KEY = process.env.WAZZUP_API_KEY;
// Секрет из параметра key в webhooksUri: подписи у Wazzup нет.
const SECRET = Buffer.from(process.env.WAZZUP_WEBHOOK_SECRET);
// Сюда пишется каждое тело до ответа 200: повтора после ошибки может не быть.
const INBOX = process.env.WAZZUP_INBOX ?? "wazzup-inbox.jsonl";

const messages = new Map(); // messageId → последнее состояние сообщения

function secretOk(got) {
  const b = Buffer.from(got ?? "");
  return b.length === SECRET.length && timingSafeEqual(b, SECRET);
}

async function sendText(channelId, chatId, text) {
  const res = await fetch("https://api.wazzup24.com/v3/message", {
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ channelId, chatType: "whatsapp", chatId, text }),
    signal: AbortSignal.timeout(10_000),
  });
  if (res.status !== 201) throw new Error(`HTTP ${res.status}`);
}

async function onMessage(m) {
  const known = messages.has(m.messageId);
  messages.set(m.messageId, { ...messages.get(m.messageId), ...m });
  if (m.isDeleted) console.log(`удалено ${m.messageId}`);
  else if (m.isEdited) console.log(`исправлено ${m.messageId}`);
  else if (known) console.log(`повтор ${m.messageId}, пропускаю`);
  else if (m.isEcho) console.log(`исходящее ${m.messageId} от ${m.authorName}`);
  else {
    console.log(`входящее ${m.type} ${m.messageId}`);
    await sendText(m.channelId, m.chatId, `Получил: ${m.text ?? m.type}`);
  }
}

async function handle(update) {
  for (const m of update.messages ?? []) await onMessage(m);
  for (const s of update.statuses ?? []) {
    messages.set(s.messageId, { ...messages.get(s.messageId), status: s.status });
    console.log(`статус ${s.messageId} → ${s.status}`);
  }
  for (const c of update.channelsUpdates ?? []) console.warn(`канал ${c.channelId} → ${c.state}`);
}

http
  .createServer((req, res) => {
    const key = new URL(req.url, "http://localhost").searchParams.get("key");
    if (req.method !== "POST" || !secretOk(key)) {
      res.writeHead(403).end();
      return;
    }
    let body = "";
    req.setEncoding("utf8");
    req.on("data", (chunk) => (body += chunk));
    req.on("end", () => {
      let update;
      try {
        update = JSON.parse(body);
      } catch {
        update = null;
      }
      if (!update || typeof update !== "object") {
        res.writeHead(400).end();
        return;
      }
      appendFileSync(INBOX, body.replace(/\n/g, " ") + "\n");
      // 200 — после записи тела, и на проверочный {"test": true} тоже.
      res.writeHead(200).end();
      if (!update.test) handle(update).catch((e) => console.error(e.cause?.code ?? e.message));
    });
  })
  .listen(8080, "127.0.0.1");

Шаг 4. Проверка без Wazzup

Запустите обработчик (python3 bot.py, php -S 127.0.0.1:8080 bot.php или node bot.mjs). Сохраните в inbound.json тело «Входящее» из раздела «Какие события присылает Wazzup» и отправьте:

bash
U="http://127.0.0.1:8080/?key=$WAZZUP_WEBHOOK_SECRET"
post() { n=$1; shift; curl -s -o /dev/null -w "$n → %{http_code}\n" -X POST -H "Content-Type: application/json" "$@"; }
post "проверка {test:true}" -d '{"test":true}' "$U"
post "входящее" --data-binary @inbound.json "$U"
post "то же ещё раз" --data-binary @inbound.json "$U"
post "чужой ключ" --data-binary @inbound.json "http://127.0.0.1:8080/?key=nope"
post "без ключа" --data-binary @inbound.json "http://127.0.0.1:8080/"
post "битое тело" -d '{не json' "$U"
post "тело null" -d 'null' "$U"

Все три обработчика отвечают одинаково:

код
проверка {test:true} → 200
входящее → 200
то же ещё раз → 200
чужой ключ → 403
без ключа → 403
битое тело → 400
тело null → 400

В журнале обработчика — входящее text d319730d-4a33-4354-8cea-458f285080a8, затем повтор d319730d-4a33-4354-8cea-458f285080a8, пропускаю, а в wazzup-inbox.jsonl — три строки: проверочное тело и оба входящих. Правку, удаление, статус и отключение канала проверьте так же, телами из того же раздела: в журнале появятся исправлено …, удалено …, статус … → read, канал … → disabled.

Шаг 5. Подписка: PATCH /v3/webhooks

Адрес приёма и туннель до обработчика — как обычно: вход, адрес (на бесплатном тарифе он один — если уже есть, возьмите токен из webhooks endpoints), туннель на 127.0.0.1:8080.

bash
webhooks login
webhooks endpoints create
webhooks tunnel --endpoint <токен адреса> --target http://127.0.0.1:8080

Подписка — PATCH /v3/webhooks:

bash
curl -X PATCH https://api.wazzup24.com/v3/webhooks \
  -H "Authorization: Bearer $WAZZUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooksUri": "https://hook.csap.ru/t/<токен>?key='"$WAZZUP_WEBHOOK_SECRET"'",
    "subscriptions": {
      "messagesAndStatuses": true,
      "contactsAndDealsCreation": false,
      "channelsUpdates": true,
      "wabaTemplatesStatus": false
    }
  }'

Ответ — OK. Перед этим, за доли секунды, Wazzup прислал на адрес проверочный запрос:

код
POST /?key=<секрет>
Content-Type: application/json
User-Agent: node-fetch/1.0 (+https://github.com/bitinn/node-fetch)

{"test":true}

Снято на локальном стенде сервиса той же версии, что hook.csap.ru: настоящие тела и заголовки запросов Wazzup от 17.10.2026, данные клиента заменены.

Если адрес ответил не 200, подписка не сохраняется:

json
{"status":400,"requestId":"18ef7cb7b00b4d62fcffd89fcf079495","error":"WEBHOOKS_REQUEST_NOT_VALID","description":"Webhooks request not valid. Response status must be 200"}

При этом прежняя настройка остаётся как была — проверено: после отказа GET /v3/webhooks вернул старый адрес. Поэтому порядок такой: сначала обработчик и туннель, потом PATCH.

Какие события присылает Wazzup

Все события — POST, Content-Type: application/json, User-Agent: node-fetch/1.0 (+https://github.com/bitinn/node-fetch). Тело — объект с массивом messages, statuses или channelsUpdates. Сняты 17.10.2026; телефоны, имя, контакт и канал заменены.

Что произошлоТелоПризнак
Клиент написалmessages[]isEcho: false, status: "inbound"
Клиент прислал фотоmessages[]type: "image", contentUri
Клиент ответил цитатойmessages[]quotedMessage — копия цитируемого сообщения
Ушло исходящее (из кабинета, с телефона, автоответ)messages[]isEcho: true, authorName
Исходящее исправленоmessages[]тот же messageId, isEdited: true, oldInfo.oldText
Исходящее удаленоmessages[]тот же messageId, isDeleted: true
Сменился статус исходящегоstatuses[]messageId, status, timestamp
Канал отключилсяchannelsUpdates[]channelId, state, timestamp в мс

Входящее:

json
{
  "messages": [{
    "messageId": "d319730d-4a33-4354-8cea-458f285080a8",
    "dateTime": "2026-10-17T07:40:00.001Z",
    "channelId": "0b1c2d3e-0000-4000-8000-000000000001",
    "chatType": "whatsapp",
    "chatId": "79000000001",
    "type": "text",
    "isEcho": false,
    "contact": {"name": "Анна Иванова", "messengerChatId": "100000000000001", "phone": "79000000001"},
    "text": "Тест",
    "status": "inbound"
  }]
}

Отвечать нужно в chatId через тот же channelId — POST /v3/message:

bash
curl -X POST https://api.wazzup24.com/v3/message \
  -H "Authorization: Bearer $WAZZUP_API_KEY" -H "Content-Type: application/json" \
  -d '{"channelId":"<channelId>","chatType":"whatsapp","chatId":"79000000001","text":"Получил"}'

Ответ — 201 и {"messageId":"…","chatId":"79000000001"}. Отправленное так сообщение тоже придёт вебхуком — эхом с isEcho: true.

Фото — то же, но "type": "image" и вместо text поле contentUri:

json
"contentUri": "https://store.wazzup24.com/<хеш>/?filename=<uuid>.jpeg"

Ссылка на файл открывается без авторизации и отдаётся с Cache-Control: public, max-age=2592000 (30 дней). Кто получил ссылку — получил файл клиента. Не пишите contentUri в журналы и открытые системы; если файл нужен дольше — скачайте к себе.

Правка исходящего — тот же messageId, что у исходного сообщения:

json
{
  "messages": [{
    "messageId": "54aba0ec-fedd-4b22-9baa-3f7d0f0231e4",
    "dateTime": "2026-10-17T07:49:00.001Z",
    "type": "text",
    "isEcho": true,
    "text": "ответ11",
    "status": "read",
    "authorName": "Admin",
    "isEdited": true,
    "isDeleted": false,
    "oldInfo": {"oldText": "ответ", "oldAuthorId": null, "oldAuthorName": null}
  }]
}

Сравнение исходящего и его правки в ленте: messageId в различиях нет — он тот же, меняются text, isEdited, isDeleted и oldInfo. Заодно видно, что в событии правки у contact нет messengerChatId.

Через четыре секунды, когда сообщение удалили, пришло оно же с "isDeleted": true и "oldInfo": {"oldText": "ответ11"}. (Поля channelId, chatType, chatId, contact в обоих событиях есть, здесь сокращены.)

Статус — отдельным событием и с задержкой: read для сообщения, ушедшего в 07:40, пришёл в 07:48.

json
{"statuses": [{"messageId": "54fa7f2f-5794-45b2-8ec3-041fc7db2bf3", "timestamp": "2026-10-17T07:40:00.004Z", "status": "read"}]}

Статус исходящего приходит и внутри самого эха ("status": "read", "delivered") — какой был на момент отправки события.

Канал отключился — событие channelsUpdates (подписка channelsUpdates: true). Пришло, когда владелец номера отключил канал (вышел из него):

json
{"channelsUpdates": [{"channelId": "0b1c2d3e-0000-4000-8000-000000000001", "state": "disabled", "timestamp": 1792224448834}]}

Здесь timestamp — целое число миллисекунд, а не строка, как в сообщениях и статусах. В GET /v3/channels у этого канала после выхода — "state": "blocked", отправка через него отвечает 404 CHANNEL_NOT_FOUND. Обработчику стоит слушать это событие: иначе бот узнает об отключённом канале только по ошибкам отправки.

dateTime и timestamp округлены до минуты и дополнены счётчиком: у трёх сообщений, пришедших в 07:40:11, 07:40:15 и 07:40:36 UTC, — 07:40:00.001Z, .002Z, .003Z. Время события по ним известно с точностью до минуты. Если важен порядок, записывайте время получения у себя. В событии statuses timestamp — время самого сообщения, а не момент, когда его прочитали.

Повторы: что делает Wazzup, если обработчик не ответил

Проверка: обработчик отвечает 500, через API уходит сообщение. Эхо пришло через 4 секунды и получило 500:

код
12:54:39 b9f1d7a5 POST    /?key=<секрет> → 500 (3ms)

(Туннель печатает местное время, UTC+5; это 07:54:39 UTC.)

За следующие 10 минут Wazzup не повторил доставку ни разу. Подписка при этом осталась включённой: когда адрес снова начал отвечать 200, эхо следующего отправленного сообщения пришло через 13 секунд после отправки. Событие, получившее 500, за 10 минут повторно не пришло; дольше наблюдение не шло.

Поэтому для Wazzup ответ 200 — не просто вежливость: рассчитывать на повтор нельзя. Отсюда правило: сначала сохранить тело как есть и ответить 200, потом разбирать. Если разбор упал — тело уже у вас, в wazzup-inbox.jsonl.

По той же причине при отладке учитывайте лимиты адреса: на бесплатном тарифе hook.csap.ru принимает до 5 запросов в секунду и 500 в месяц, сверх этого отвечает 429. Как Wazzup поступает с 429, не проверялось; после 500 повтора не было. Для потока сообщений — платный тариф (на «Индивидуальном» 10 в секунду и 20 000 в месяц, тарифы) или свой сервер.

С localhost на сервер

  • В webhooksUri — адрес вашего сервера с секретом; новый адрес ставится тем же PATCH, и Wazzup снова пришлёт {"test":true}.
  • Обработчик отвечает 200 на {"test":true} всегда — иначе смена адреса не пройдёт.
  • Тело события сохраняется как есть до разбора: повтора после ошибки может не быть.
  • Сообщения — в базе с первичным ключом messageId; правка и удаление обновляют строку, а не создают новую.
  • Эхо (isEcho) не запускает логику бота.
  • contentUri не уходит в журналы; нужные файлы скачиваются к себе.
  • Время события — время получения на вашей стороне; dateTime — только для показа.

Как выключить вебхук

Сбросить адрес через API нельзя: "webhooksUri": null, пустая строка и запрос без адреса получают 400 INVALID_WEBHOOKS_DATA, а DELETE /v3/webhooks отвечает 404. Выключаются подписки — с тем же адресом:

bash
curl -X PATCH https://api.wazzup24.com/v3/webhooks \
  -H "Authorization: Bearer $WAZZUP_API_KEY" -H "Content-Type: application/json" \
  -d '{"webhooksUri":"<текущий адрес>","subscriptions":{"messagesAndStatuses":false,"contactsAndDealsCreation":false,"channelsUpdates":false,"wabaTemplatesStatus":false}}'

Ответ — OK, GET /v3/webhooks показывает все четыре подписки false. Проверочного {"test":true} при выключении на адрес не пришло. Адрес остаётся в настройке — если в нём секрет, учтите: адрес вместе с секретом остаётся в настройках Wazzup и виден там, поэтому при следующем включении задайте новый.

Симптом → причина

СимптомПричинаПроверка
PATCH отвечает 400 INVALID_WEBHOOKS_DATA, "data":["webhooksUri"]В запросе нет поля webhooksUri: опечатка webhooksUrl, null или пустая строкаИмя поля в теле запроса
PATCH отвечает 400 WEBHOOKS_REQUEST_NOT_VALIDАдрес ответил на {"test":true} не 200: обработчик не запущен, нет туннеля, неверный ключЛента адреса: запрос {"test":true} и его код
Бот отвечает сам себе бесконечноОбработчик не пропускает isEcho: trueПоле isEcho у событий в ленте
Правка или удаление «потерялись»Обработчик выбросил их как повтор по messageIdДва события с одним messageId и isEdited/isDeleted
Порядок сообщений перепутанСортировка по dateTime, а оно округлено до минутыВремя получения в ленте против dateTime
Обработчик отвечает 403 на всёkey в webhooksUri и в переменной разныйGET /v3/webhooks — адрес целиком
Статуса read нет сразуСтатусы приходят отдельно и с задержкойСобытие statuses позже эха
Событие не пришло повторноОбработчик ответил 500 — за 10 минут Wazzup его не повторилКод ответа у события в ленте; тело — в wazzup-inbox.jsonl

Вопросы

Есть ли у Wazzup подпись вебхука? При подключении по ключу API — нет: в запросе только заголовки трассировки и User-Agent: node-fetch/1.0. Защита — секрет в параметре адреса.

Можно ли поставить адрес, который пока не отвечает? Нет: при PATCH Wazzup проверяет адрес запросом {"test":true} и без ответа 200 подписку не сохраняет.

Почему одно и то же сообщение пришло несколько раз? Если отличаются isEdited, isDeleted или text — это правка или удаление. Повторной доставки на проверке не было; отсев по messageId — защита на случай, если она случится.

Повторит ли Wazzup событие, если сервер ответил ошибкой? На проверке — нет: за 10 минут после ответа 500 повтора не было. Сохраняйте тело до ответа и отвечайте 200 сразу.

Почему PATCH /v3/webhooks отвечает 400 INVALID_WEBHOOKS_DATA? Поле адреса называется webhooksUri — с i на конце. С webhooksUrl Wazzup отвечает 400 INVALID_WEBHOOKS_DATA и подсказывает "data":["webhooksUri"]; та же ошибка на null и пустую строку.

Как отключить вебхук Wazzup? Выключить все подписки тем же PATCH /v3/webhooks с текущим адресом. Сбросить сам адрес API не даёт: null, пустая строка и запрос без адреса получают 400 INVALID_WEBHOOKS_DATA.

Как отличить ответ оператора от автоответа? По authorName: на проверке ответ из кабинета пришёл с "Admin", отправленное с телефона — с "Phone", у автоответа поле было пустым.

Ещё по теме

Все руководства
HTTP-уведомление ЮKassa в ленте hook.csap.ru

Не приходят HTTP-уведомления ЮKassa: где теряется вебхук и как это проверить

Не приходят уведомления ЮKassa? Симптомы и причины, проверка адреса, TLS и кода ответа, повторы до 24 часов и обработчик, который не отметит заказ дважды.

  • юkassa
  • http-уведомления
  • вебхуки
  • платежи
  • отладка
Cookie и Яндекс Метрика

Мы хотим подключить Яндекс Метрику: она ставит cookie и помогает понять, как посетители пользуются сайтом. Метрика заработает, только если вы разрешите. Без неё сервис работает так же. Политика обработки данных