Номера для входящих и вебхуки входящих сообщений

На странице Номера для входящих вы выбираете, какие из ваших номеров WhatsApp синхронизируются во входящие Unibox, где ваша команда читает их чаты и отвечает на них. Укажите для номера URL вебхука, и WbizTool будет также отправлять на ваш сервер каждое новое полученное или отправленное им сообщение в виде подписанного JSON: записывайте переписку в CRM, оповещайте команду или запускайте автоответ.

Пишете приёмник? Перейдите к разделам Как доставляются вебхуки, Проверка подписи и Полезная нагрузка.

Кто может это делать: владельцы и редакторы добавляют номера, меняют вебхуки и видят секрет вебхука. Аналитики не видят пункта Номера для входящих в боковом меню. Нужно дополнение Unibox: $20 в месяц или $200 в год по базовым ценам в США за каждый номер во входящих (ваша цена указана на странице Оплата и тарифы); его подключает владелец на странице Оплата и тарифы к платному или пожизненному тарифу (см. Дополнения). Количество единиц дополнения — это сколько номеров может быть во входящих одновременно.

Откройте Номера для входящих в разделе Входящие бокового меню или перейдите на /unibox/listeners/.

Перед началом работы#

• Дополнение Unibox со свободным номером для входящих: строка под заголовком страницы показывает, например, «Используется 2 из 3 номеров для входящих (дополнение Unibox)» или «Нет дополнения Unibox» (см. Без дополнения Unibox).
• Номер WhatsApp, подключённый по QR-коду или коду привязки, со статусом Подключён на странице Номера WhatsApp. Номера, подключённые через расширение браузера, добавить нельзя. Подключённый аккаунт Telegram добавляется так же, как номер.
• Для вебхука: адрес https:// длиной не более 500 символов в публичном интернете (не localhost и не частная сеть), который принимает запросы POST с телом JSON и отвечает 2xx в течение 8 секунд.

Добавление номера во входящие#

1. Откройте окно

   Нажмите Добавить номер во входящие в правом верхнем углу страницы.

2. Выберите номер

   Выберите его в поле Номер WhatsApp. В списке — ваши подключённые номера, которых ещё нет во входящих.

3. Добавьте вебхук (необязательно)

   Введите адрес в поле URL вебхука (необязательно). Появится блок Какие сообщения отправлять: оставьте отмеченными Полученные сообщения, Отправленные сообщения или оба пункта. Вебхук можно добавить или изменить и позже.

   

4. Добавьте номер

   Нажмите Добавить номер. Появится «Номер добавлен – его чаты начнут синхронизироваться в течение нескольких минут.» Если вы ввели URL вебхука, откроется окно Ваш секрет вебхука: нажмите Копировать и сохраните секрет там, где его сможет прочитать ваш сервер. Позже его можно снова посмотреть в настройках вебхука.

• Только новые сообщения. Номер синхронизируется с момента добавления: более старые сообщения не импортируются и не отправляются.
• Все номера заняты? Окно сообщает «Все ваши номера для входящих заняты. Остановите или удалите один из них либо добавьте номера в дополнение Unibox.» Остановите или удалите номер либо попросите владельца увеличить количество единиц дополнения (Посмотреть дополнения).
• Повторное добавление удалённого номера возвращает его входящие («Номер снова добавлен – его чаты снова синхронизируются с этого момента.»); сообщения за то время, пока номер был удалён, не подтягиваются. С URL вебхука номер сохраняет прежний секрет, если он был (используйте Показать в окне Настройки вебхука); иначе откроется окно Ваш секрет вебхука с новым секретом.

Что показывает карточка номера#

На каждой карточке — номер, время, когда WbizTool последний раз проверял его сообщения («Последняя проверка: 1 мин назад» или Ещё не проверялся), Сообщения и Синхронизировано контактов (все чаты, синхронизированные с номера, включая те, где во входящих нет сообщений), Последнее сообщение и Вебхук: URL и то, что на него отправляется, например «Отправляет каждое полученное и отправленное сообщение · подписан секретом» или «Нет – сообщения видны только во входящих.» Значок Zapier означает, что сообщения получает Zap (см. Zapier и номера для входящих).

Значок в правом верхнем углу показывает, что происходит с номером:

Изменение URL вебхука или отправляемых сообщений#

1. Откройте настройки вебхука

   Нажмите Настройки вебхука на карточке номера.

2. Измените настройки

   Отредактируйте URL вебхука (необязательно) и отметки в блоке Какие сообщения отправлять. Чтобы отключить вебхук, очистите URL.

3. Сохраните

   Нажмите Сохранить. Появится «Настройки вебхука сохранены.»

   

• При изменении URL секрет сохраняется. При очистке URL он удаляется; URL, добавленный позже, получит новый секрет, который один раз покажется в окне Ваш секрет вебхука.
• Если не отмечен ни один пункт, на карточке написано «События не выбраны – ничего не отправляется».

Показ и повторная генерация секрета#

Секрет состоит из 32 букв и цифр. В окне Настройки вебхука в поле Секрет вебхука кнопка Показать открывает его, а рядом появляется Копировать. Сгенерировать заново спрашивает «Сгенерировать новый секрет? Текущий сразу перестанет работать – обновите его везде, где проверяете подписи.» Нажмите Сгенерировать новый секрет: он сохраняется сразу («Новый секрет сгенерирован.»), без Сохранить, и все запросы с этого момента подписываются им, включая повторы более ранних сообщений.

Остановка, запуск и удаление номера#

Вебхуки, ожидающие повтора, отбрасываются, когда вы останавливаете или удаляете номер либо меняете его URL.

Как доставляются вебхуки#

• Когда: каждый номер для входящих проверяется примерно раз в минуту, пока он подключён; проверки приостанавливаются, пока он отправляет сообщения, например кампанию. Сообщение отправляется после проверки, которая его нашла, обычно в течение одной-двух минут. Кнопки для теста нет: отправьте на номер сообщение с другого телефона.
• Один запрос на сообщение: message_received для Полученные сообщения; message_sent для Отправленные сообщения — отправленных с телефона, из WhatsApp Web или самим WbizTool (кампании, API, напоминания). Ответы, отправленные из входящих Unibox, обычно не передаются: во входящих они уже есть.
• Успех: любой статус 2xx в течение 8 секунд. Перенаправления не выполняются: 3xx считается ошибкой.
• Повторы: при тайм-ауте, ошибке соединения, 429 или 5xx запрос повторяется 3 раза — через 30 секунд, 1 минуту и 2 минуты. Другие ответы, например 400 или 404, и недействительный TLS-сертификат не повторяются.
• 410 Gone: WbizTool отключает вебхук номера (URL и секрет удаляются; для хука Zapier возвращается ваш собственный прежний вебхук). Номер продолжает синхронизироваться во входящие.
• Порядок и дубли: запросы могут приходить не по порядку и изредка дважды. Сортируйте по message.whatsapp_timestamp и пропускайте message.id, который вы уже обработали для того же whatsapp_client_id. Если два ваших номера состоят в одной группе, каждый отправляет свою копию.
• Запоздавшие сообщения: сообщение, подтянутое с опозданием, например после переподключения номера или паузы в проверках, всё равно отправляется, и если ему больше 10 минут, в нём replayed равно true. Сообщения, пришедшие, пока номер был остановлен, после Запустить не отправляются (см. Остановка, запуск и удаление номера).
• Проверка адреса: URL проверяется заново перед каждым запросом; на хост, который теперь указывает на частную сеть или не разрешается, ничего не отправляется, и это сообщение не повторяется.

Заголовки#

Проверка подписи#

Каждый запрос подписывается секретом вебхука номера по алгоритму HMAC-SHA256 от сырого тела запроса точно в том виде, в каком оно пришло. Шестнадцатеричный дайджест в нижнем регистре передаётся в X-Wbiztool-Signature как sha256=<digest>. У вебхука, заданного на странице Номера для входящих, секрет есть всегда, поэтому заголовок присутствует всегда.

Вычисляйте подпись по сырым байтам до разбора JSON. Разбор и повторное кодирование меняют тело (пробелы, экранированные символы), и подпись не совпадёт.

// Express: register this route before app.use(express.json()), or the raw body is lost
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WBIZTOOL_WEBHOOK_SECRET;

app.post("/wbiztool/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Wbiztool-Signature") || "";

  const a = Buffer.from(received), b = Buffer.from(expected);
  const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
  if (!valid) return res.status(401).send("Invalid signature");

  const data = JSON.parse(req.body.toString("utf8"));
  if (data.event === "message_received") {
    console.log(`New message from ${data.contact.phone}: ${data.message.content}`);
  }
  res.sendStatus(200); // answer quickly; do slow work in the background
});

app.listen(3000);

# Flask
import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["WBIZTOOL_WEBHOOK_SECRET"].encode()


@app.post("/wbiztool/webhook")
def wbiztool_webhook():
    raw_body = request.get_data()  # raw bytes, before parsing
    expected = "sha256=" + hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Wbiztool-Signature", "")
    if not hmac.compare_digest(expected, received):
        abort(401)

    data = json.loads(raw_body)
    if data["event"] == "message_received":
        print(f"New message from {data['contact']['phone']}: {data['message']['content']}")
    return "", 200

<?php
$secret   = getenv('WBIZTOOL_WEBHOOK_SECRET');
$rawBody  = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$received = $_SERVER['HTTP_X_WBIZTOOL_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($rawBody, true);
if ($data['event'] === 'message_received') {
    error_log('New message from ' . $data['contact']['phone'] . ': ' . $data['message']['content']);
}
http_response_code(200);

Чтобы проверить приёмник до прихода настоящего сообщения, подпишите тело сами и отправьте его:

BODY='{"event":"message_received","message":{"content":"Test"},"contact":{"phone":"12125550120"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WBIZTOOL_WEBHOOK_SECRET" | sed 's/^.* //')
curl -X POST https://your-server.example/wbiztool/webhook -H 'Content-Type: application/json' -H "X-Wbiztool-Signature: sha256=$SIG" -d "$BODY"

Подпись покрывает тело, включая его timestamp, который меняется при каждой попытке. Чтобы отклонять повторно отправленные запросы, отбрасывайте timestamp старше 5 минут и пропускайте message.id, который уже обработали.

Полезная нагрузка#

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:30:31.482913+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0C1A2B3D4E5F60718",
    "type": "chat",
    "content": "Can I add a gift note to it?",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:30:04+00:00",
    "whatsapp_timestamp": 1792060204,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_sent",
  "timestamp": "2026-10-15T10:34:22.117205+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0F9E8D7C6B5A40312",
    "type": "chat",
    "content": "Of course! Send us the text and we'll print it on a card.",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:33:40+00:00",
    "whatsapp_timestamp": 1792060420,
    "direction": "outgoing",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:35:48.904311+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0A7B6C5D4E3F20109",
    "type": "image",
    "content": "📸 Image",
    "from": "12125550122",
    "from_name": "Sofia Martinez",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:34:51+00:00",
    "whatsapp_timestamp": 1792060491,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "media": {
      "filename": "",
      "mimetype": "image/jpeg",
      "size": 245760,
      "url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/unibox/10314/media/false_12125550122%40c.us_3EB0A7B6C5D4E3F20109.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=…&X-Amz-Date=20261015T103548Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=…"
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550122",
    "lid": null,
    "phone_hidden": false,
    "name": "Sofia Martinez",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:39:40.330187+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected][email protected]",
    "type": "chat",
    "content": "Will there be a larger size?",
    "from": "120363041234567890",
    "from_name": "Lumen VIP Club",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:39:02+00:00",
    "whatsapp_timestamp": 1792060742,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "sender": {
      "phone": "12125550126",
      "name": "Olivia Brooks",
      "phone_hidden": false
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "120363041234567890",
    "lid": null,
    "phone_hidden": false,
    "name": "Lumen VIP Club",
    "is_group": true,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  },
  "group": {
    "name": "Lumen VIP Club"
  }
}

Номера, ID и имена выше — примеры. Настоящее тело — одна строка компактного JSON, и каждый не-ASCII-символ (буквы с диакритикой, кириллица и другие письменности, эмодзи) приходит как экранированная последовательность \uXXXX, например \ud83d\udcf8 для 📸. Могут добавиться новые поля; игнорируйте те, которые не используете.

Поля верхнего уровня#

Поля message#

Поля contact#

Zapier и номера для входящих#

Триггер WbizTool Incoming WhatsApp Message в Zapier использует эти вебхуки. При включении Zap номер при необходимости добавляется во входящие (занимая один из ваших номеров для входящих), а его вебхук направляется в Zapier — только для полученных сообщений и с собственным секретом; на карточке появляется значок Zapier. Ваши собственные URL вебхука, секрет и отметки возвращаются, когда Zap выключают.

Окно Настройки вебхука тогда предупреждает: «Этот вебхук принадлежит Zap в Zapier. Если изменить или удалить URL, Zap перестанет получать сообщения.» Остановить и Удалить тоже предупреждают: Zap в Zapier останется включённым, но ничего не будет получать, поэтому лучше выключите его в Zapier. См. Как триггер работает с номерами для входящих.

Без дополнения Unibox#

Страница показывает «Нет дополнения Unibox» и «Дополнение Unibox не активно в этом пространстве.», а Добавить номер во входящие открывает окно Нужно дополнение Unibox: «Чтобы добавлять номера WhatsApp в общие входящие и получать их сообщения через вебхук, подпишитесь на дополнение Unibox.» Владелец нажимает Посмотреть дополнения и добавляет дополнение Номер для Unibox на странице Оплата и тарифы к платному или пожизненному тарифу (не в пробном периоде).

Если дополнение закончилось или номер отключился#

• Дополнение закончилось: каждый номер для входящих останавливается — сразу или примерно в течение часа. На карточках — Остановлен с пояснением «Остановлен, потому что дополнение Unibox не активно в этом пространстве.» Владельцы и редакторы узнают, какие входящие остановлены, из письма об оплате или из уведомления «Часть номеров или функций … остановлена» (Проблемы с номером и отправкой в разделе Уведомления). Переписки, URL вебхуков и секреты сохраняются: когда дополнение снова активно, нажмите Запустить у каждого номера. Сообщения за время остановки затем добавляются во входящие (до 30 дней назад), но не отправляются на ваш вебхук.
• Дополнение покрывает меньше номеров, чем включено: «Включено больше номеров, чем позволяет ваше дополнение. Самые новые лишние номера будут автоматически остановлены примерно в течение часа.»
• Номер отключился: на карточке — Номер отключён, ничего не синхронизируется и не отправляется. После переподключения сообщения, пришедшие за это время, тоже подтягиваются и отправляются; у тех, что старше 10 минут, replayed равно true.
• Номер переподключён к другому телефону: номер для входящих и его вебхук с этого момента продолжают работать для нового номера (тот же whatsapp_client_id, новый whatsapp_phone); старые чаты остаются во входящих как история.

Устранение неполадок#

Связанные материалы#

• Входящие Unibox: чтение чатов ваших номеров для входящих и ответы на них
• Интеграция с Zapier
• Подключение номера WhatsApp
• Тарифы и оплата
• API отправки сообщений: его поле webhook сообщает, ушло ли отправленное вами сообщение (это другой вебхук)