ВойтиНачать бесплатный пробный период
Meta Tech Provider

Как сообщения WhatsApp доходят до вашего сервера: напрямую или через управляемый режим, и проверка подписи

У каждого номера, подключённого через easyCoexistence, есть один входящий режим. Straight to your system (прямой режим): Meta отправляет вебхуки на ваш HTTPS-эндпоинт, секрет в URL служит учётными данными, а автоматизации выключены. Through easyCoexistence (управляемый режим): Meta доставляет данные в easyCoexistence, автоматизации могут отвечать, а необязательный Forward URL получает исходное значение Meta с данными подключения, подписанное заголовком X-EC-Signature для проверки на вашей стороне.

7 attempts

Попыток на каждую пересланную доставку, с интервалами 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч, всего около 33 часов.

10 s

Сколько времени каждая попытка пересылки ждёт ответа 2xx, прежде чем считается неудачной.

5 min

Рекомендуемое ограничение на возраст t в подписи; повторы подписываются заново, поэтому подлинные доставки в него укладываются.

7 days

Сколько Meta повторяет прямой вебхук, получивший что-либо кроме HTTP 200; повторы могут дублировать сообщения.

3 MB

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

30 days

Журналы запусков для управляемого номера хранятся с текстом сообщений и ответов; сам текст сообщений хранится 30, 90 или 365 дней на ваш выбор.

В чём разница между прямым и управляемым режимом?

Куда Meta доставляет вебхуки сообщений номера. Управляемый режим, который отображается как Through easyCoexistence, означает, что Meta доставляет данные в easyCoexistence. Сервис проверяет подпись Meta, запускает ваши автоматизации, хранит чаты для Conversations и, если вы указали Forward URL, передаёт каждое изменение Meta дальше, подписанным секретом, который известен только вам. Прямой режим, отображаемый как Straight to your system, означает, что easyCoexistence задаёт ваш HTTPS-эндпоинт как переопределение вебхука в аккаунте WhatsApp Business номера, поэтому Meta отправляет данные прямо вам, и сообщения никогда не попадают в easyCoexistence.

Служебные вебхуки, на которых работает мониторинг, например account_update и изменения качества, остаются в easyCoexistence в обоих режимах, поэтому оповещения работают в любом случае.

Managed: Through easyCoexistenceDirect: Straight to your system
Meta delivers toeasyCoexistence, which verifies Meta's signatureYour HTTPS endpoint
AutomationsRun on the numberOff
Your copyOptional Forward URL, one Meta change per POSTMeta's envelope, unchanged
Proof it is genuineX-EC-Signature, HMAC-SHA256 with the number's secretA long random secret in the URL path
Failed deliveries7 attempts over about 33 hoursMeta retries for up to 7 days
History importNot requestedRequested when saved within 24 hours of connecting
Kept by easyCoexistenceMessage text 30, 90 or 365 days, run logs 30 daysNothing

Как переключить номер между режимами?

На странице номера карточка Where incoming messages go показывает режим в виде двух вариантов: Through easyCoexistence и Straight to your system. Сохранение адреса вебхука в карточке Route incoming messages to your own webhook или через set_webhook_destination делает номер прямым. Выбор Through easyCoexistence сразу удаляет этот адрес у Meta, поэтому добавьте тот же URL как Forward URL, чтобы продолжить получать данные. Поставленные в очередь пересылки отбрасываются, когда номер покидает управляемый режим, а номера, подключённые без URL вебхука, начинают в управляемом режиме.

Из вашего ИИ-ассистента set_inbound_mode переключает режим и задаёт пересылку одним вызовом и возвращает секрет пересылки один раз:

set_inbound_mode: arguments and result
// set_inbound_mode arguments
{
  "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "mode": "managed",
  "forward_url": "https://agent.example.com/ec/forward"
}

// result: forward_secret is shown once
{
  "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "mode": "managed",
  "forward_url": "https://agent.example.com/ec/forward",
  "forward_secret": "whsec_Qm9vbXRoZXNlY3JldHNhcmVmYWtlMTIz",
  "secret_note": "Shown once. Verify X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with it; the body's value is Meta's original payload.",
  "direct_destination": null
}

Что содержит пересланный POST?

Одно изменение Meta на запрос, в обёртке, а не в конверте Meta с object, entry и changes. id это идентификатор доставки, он повторяется в X-EC-Delivery и стабилен между повторами. event это имя поля Meta: messages, smb_message_echoes, history или smb_app_state_sync, повторяется в X-EC-Event. received_at это время, когда easyCoexistence получил изменение от Meta, connection указывает на номер, а value содержит в точности то, что отправила Meta, поэтому код разбора, написанный под полезную нагрузку Meta, работает и с ней. Статусы доставки приходят внутри событий messages, в value.statuses.

A forwarded messages event: headers and body
POST /ec/forward HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-forward/1
X-EC-Event: messages
X-EC-Delivery: 8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13
X-EC-Signature: t=1794405732,v1=<64 hex characters>

{
  "id": "8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13",
  "event": "messages",
  "received_at": "2026-11-11T14:02:11.482Z",
  "connection": {
    "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
    "phone": "+1 631-555-0142",
    "phone_number_id": "106540352242922",
    "waba_id": "102290129340398",
    "external_ref": null
  },
  "value": {
    "messaging_product": "whatsapp",
    "metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
    "contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
    "messages": [{
      "from": "5511987654321",
      "from_user_id": "BR.13491208655302741918",
      "id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
      "timestamp": "1794405731",
      "type": "text",
      "text": { "body": "Do you deliver on Sundays?" }
    }]
  }
}

Как проверить X-EC-Signature в Node.js?

Прочитайте заголовок как t=<unix seconds>,v1=<64 hex characters>. Отклоните t, которое отличается от вашего времени более чем на 5 минут, вычислите HMAC-SHA256 над t, точкой и исходным телом, с ключом, которым служит весь секрет пересылки в виде текста UTF-8, и сравните результат с v1 за постоянное время. Только после этого разбирайте JSON. Отвечайте 2xx в течение 10 секунд, а работу выполняйте потом, и запоминайте идентификаторы принятых доставок, чтобы повтор не обрабатывался дважды.

forward-receiver.mjs (Node.js, no dependencies)
// forward-receiver.mjs: node forward-receiver.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";

const SECRET = process.env.EC_FORWARD_SECRET; // the whole whsec_... string is the HMAC key
const taken = new Set(); // delivery ids already accepted: use a database in production

export function verifyEcSignature(raw, header, secret = SECRET, maxAgeSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
  if (!m || !secret) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > maxAgeSec) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
  return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    if (req.method !== "POST" || !verifyEcSignature(raw, req.headers["x-ec-signature"])) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(200).end(); // a 2xx within 10 s, before any work
    const d = JSON.parse(raw.toString("utf8"));
    if (taken.has(d.id)) return; // a retry of a delivery already accepted
    taken.add(d.id);
    // d.event is the Meta field (messages, smb_message_echoes, history, smb_app_state_sync)
    // d.value is Meta's change value, unchanged; queue it for your worker here.
    console.log(d.event, d.connection.phone_number_id, Object.keys(d.value));
  });
}).listen(process.env.PORT ?? 3000);

Как проверить в Python?

Те же четыре проверки на стандартной библиотеке: строгий шаблон заголовка, возраст t, hmac.new над t, точкой и исходными байтами, и hmac.compare_digest. В FastAPI исходное тело берётся из await request.body(), а BackgroundTasks выполняет работу после отправки 200. В Flask используйте request.get_data() и никогда не пересобирайте тело через json.dumps, потому что разделители Python по умолчанию добавляют пробелы, и подпись перестаёт совпадать.

forward_receiver.py (FastAPI)
# forward_receiver.py: pip install fastapi uvicorn, then uvicorn forward_receiver:app
import hashlib, hmac, json, os, re, time
from fastapi import BackgroundTasks, FastAPI, Request, Response

app = FastAPI()
SECRET = os.environ["EC_FORWARD_SECRET"].encode()  # the whole whsec_... string, as bytes
SIGNATURE = re.compile(r"t=([0-9]+),v1=([0-9a-f]{64})")
taken = set()  # delivery ids already accepted: use a database in production

def verify_ec_signature(raw: bytes, header: str, max_age: int = 300) -> bool:
    m = SIGNATURE.fullmatch(header.strip())
    if not m or abs(int(time.time()) - int(m[1])) > max_age:
        return False
    mac = hmac.new(SECRET, m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, m[2])

def process(delivery: dict) -> None:
    if delivery["id"] in taken:  # a retry of a delivery already accepted
        return
    taken.add(delivery["id"])
    print(delivery["event"], delivery["connection"]["phone_number_id"], list(delivery["value"]))

@app.post("/ec/forward")
async def forward(request: Request, tasks: BackgroundTasks):
    raw = await request.body()
    if not verify_ec_signature(raw, request.headers.get("x-ec-signature", "")):
        return Response(status_code=401)
    tasks.add_task(process, json.loads(raw))  # runs after the 200 goes out
    return Response(status_code=200)

Как повторяются неудачные доставки?

Пересылка считается доставленной, когда ваш эндпоинт отвечает любым 2xx в течение 10 секунд. Любой другой исход, таймаут, 4xx, 5xx или перенаправление, которое не отслеживается, ставит следующую попытку примерно через 1 минуту, 5 минут, 30 минут, 2 часа, 6 часов и 24 часа, а после седьмой попытки доставка отбрасывается. Каждая попытка подписывается заново со свежим t, а URL должен быть публичным HTTPS, проверяется при сохранении и снова перед каждой отправкой. Доставки уходят от старых к новым, но повторённая может прийти после более новых, поэтому сортируйте по временным меткам Meta.

Для прямого адреса повторы делает Meta: любой ответ, кроме HTTP 200, повторяется с уменьшающейся частотой в течение до 7 дней, и эти повторы могут дублировать сообщение. В обоих режимах дедуплицируйте по идентификатору сообщения Meta, так как изменение, которое Meta доставила повторно, пересылается снова под новым идентификатором доставки.

Как прямой эндпоинт понимает, что POST подлинный?

Не по X-Hub-Signature-256. Meta подписывает секретом приложения, которому принадлежит подписка; для номера, подключённого здесь, это приложение easyCoexistence, и его секрет не передаётся, поэтому проверка этого заголовка вашим секретом приложения Meta отклоняет подлинные доставки. Verify token подтверждает эндпоинт только один раз, во время GET-рукопожатия Meta. Что работает вместо этого:

  • Добавьте 32 и более случайных символа в путь URL обратного вызова и отклоняйте запросы без них; для смены сохраните новый URL.
  • Используйте обобщённый приёмник, например узел Webhook в n8n, а не триггер WhatsApp, который ожидает ваше собственное приложение Meta.
  • Скачивайте медиа по идентификатору из Meta с токеном номера, поэтому подделанный идентификатор просто не сработает.
  • На собственных серверах можно разрешить только сеть Meta, то есть маршруты, объявленные AS32934.
  • Или перейдите на управляемый режим с Forward URL, где X-EC-Signature подтверждает каждый POST.

Распространённые ошибки

  • Код, написанный под конверт Meta, направлен на Forward URL без изменений. Пересылка несёт одно изменение: читайте event и value, а не object, entry и changes.
  • Ожидание X-EC-Event со значением statuses. Статусы доставки приходят внутри событий messages, в value.statuses, а ответы, набранные в приложении, приходят как smb_message_echoes.
  • Работа до ответа. Пересылка ждёт 10 секунд, затем та же доставка возвращается с новым t; сначала отвечайте 2xx и обрабатывайте из очереди.
  • Переход на управляемый режим с расчётом, что старый URL продолжит получать данные. Прямой адрес удаляется в этот момент; передайте forward_url в том же вызове set_inbound_mode.
Настройка с EasyCoexistence

easyCoexistence подключает номер приложения WhatsApp Business к Cloud API Meta через Coexistence и позволяет выбрать для каждого номера, куда идут его сообщения: напрямую от Meta на ваш сервер или через easyCoexistence, чтобы автоматизации могли отвечать, а подписанная копия доходила до вашего Forward URL. Мониторинг и оповещения работают в обоих режимах. От US$ 9 до US$ 0,75 за подключённый номер в месяц, с понижением по мере добавления номеров, и бесплатный пробный период: первые 3 дня.

Часто задаваемые вопросы

Увидит ли мой сервер, что ответила автоматизация?

Не текст. Meta передаёт отправки через API как статусы (отправлено, доставлено, прочитано) внутри событий messages, с идентификатором сообщения; сам текст хранится в журнале запусков автоматизации, который хранится 30 дней на вкладке Runs, и в Conversations в течение выбранного вами срока.

Как сменить секрет пересылки?

Нажмите New secret на странице номера или вызовите set_inbound_mode с rotate_secret, равным true. Новый секрет показывается один раз и подписывает всё с этого момента, включая повторы более старых доставок, поэтому сразу обновите сервер.

Нужно ли Forward URL рукопожатие GET от Meta?

Нет. Только прямой адрес вызывается Meta и должен возвращать hub.challenge. Forward URL вызывается easyCoexistence и получает только подписанные POST.

Может ли у номера одновременно быть прямой адрес и Forward URL?

Нет. Forward URL работает только пока номер управляемый, а сохранение прямого адреса делает номер прямым. Forward URL и его секрет сохраняются, поэтому переключение обратно в управляемый режим возобновляет пересылку.

Читайте дальше

ИИ-агент для WhatsApp на Node.js и Python на номере CoexistenceКод на Node.js и Python для ИИ-агента на номере Coexistence: проверка подписанных событий, пауза при ответе человека, пропуск дублей и проверка окна.WhatsApp AI-агент в n8n: ответ пишет ваш сценарийЗапустите AI-агента WhatsApp в n8n: подписанный POST передаёт сообщение и недавний чат, узел AI Agent пишет ответ, и он возвращается в течение 20 секунд.Дайте ИИ-агенту память: шесть месяцев чатов и контактов WhatsAppЗагрузите до 180 дней чатов WhatsApp и контакты в память ИИ-агента на номере Coexistence: правило 24 часов, фрагменты, прогресс и хранение.Вебхуки WhatsApp: маршрутизация сообщений на ваш серверКак работают вебхуки WhatsApp, что отправляет Meta и как направить входящие сообщения прямо на ваш эндпоинт, минуя платформу провайдера.Проверка эндпоинта вебхука WhatsAppMeta отправляет на ваш эндпоинт GET-проверку до доставки событий. Что приходит, что вернуть и почему неверный ответ не вызывает ошибки.ИИ и человек на одном номере WhatsApp: ИИ отступает, когда вы ответите с телефонаЗапускайте ИИ и сами отвечайте клиентам на одном номере WhatsApp Business. Ответ с телефона ставит автоматизации на паузу в чате, по умолчанию на 4 часа.

Готовы начать?

Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.

Начать бесплатный пробный период

Проверено по состоянию на