Как получать сообщения клиентов WhatsApp и комментарии соцсетей по вебхуку
Каждое подключение получает собственный вебхук для сообщений клиентов WhatsApp или комментариев из соцсетей через Partner API easyCoexistence. Сообщения WhatsApp поступают от Meta напрямую на этот URL и подписаны секретом приложения Tech Provider, а не секретом, которым владеете вы, поэтому аутентифицирует их длинный случайный секрет в пути URL. Комментарии и DM из Instagram и Facebook, а также комментарии TikTok пересылаются по мере поступления и подписываются для каждого аккаунта заголовком X-EC-Signature.
Максимальная длина, которую Meta допускает для альтернативного URL обратного вызова, по которому сообщения номера поступают на ваш эндпоинт.
Срок, в течение которого Meta повторно отправляет вебхук WhatsApp, который ваш эндпоинт не принял, с всё более редкими интервалами; из-за этого возможны дубликаты.
Сеть Meta; whois-запросы маршрутов к ней показывают адреса, с которых приходят вебхуки WhatsApp, и Meta периодически их меняет.
Максимальный размер полезной нагрузки вебхука WhatsApp по данным Meta.
Возраст, после которого подписанная метка времени пересланного события должна отклоняться, при этом HMAC сравнивается за постоянное время.
Как каждое подключение получает собственный адрес назначения?
Через один вызов на каждый ресурс. Номер WhatsApp принимает PUT /connections/{id}/webhook с полями url и verify_token или ту же пару как webhook_url и webhook_verify_token в сессии подключения, так что номер направляется к вам с первой минуты. Аккаунт соцсети принимает PUT /channels/{id}/webhook после подключения. Значение null в url на любом из них отключает доставку. Два пути различаются тем, кто доставляет и как вы проверяете подлинность:
| WhatsApp number | Instagram, Facebook, TikTok | |
|---|---|---|
| Set with | webhook_url on the session, or PUT /connections/{id}/webhook | PUT /channels/{id}/webhook, after it connects |
| Delivered by | Meta, straight to your URL | easyCoexistence, forwarding each event as it arrives |
| Body | Meta's webhook, unchanged | platform, account_id, external_id and the network's entry |
| Authenticate | A long random secret in the URL path | X-EC-Signature, keyed with the account's secret |
| Retries | Meta's own, for up to 7 days | None: one attempt |
| Copy kept | None | None |
Как направить сообщения номера на ваш эндпоинт?
Укажите HTTPS URL, в пути которого есть длинный случайный секрет, и токен проверки: webhook_verify_token в сессии подключения, от 8 до 200 символов, или verify_token в PUT. Meta сразу проверяет URL GET-запросом с hub.mode=subscribe, hub.verify_token и hub.challenge, и ваш эндпоинт должен вернуть значение hub.challenge, если токен совпадает. Если это рукопожатие не проходит, PUT возвращает 502 meta_rejected с собственным сообщением Meta; в сессии подключения номер всё равно подключается, а last_error сессии объясняет, почему URL не применён.
import express from "express";
import { timingSafeEqual } from "node:crypto";
const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();
function same(a, b) {
const x = Buffer.from(String(a)), y = Buffer.from(String(b));
return x.length === y.length && timingSafeEqual(x, y);
}
// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
return res.sendStatus(403);
}
res.send(req.query["hub.challenge"]);
});
// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
res.sendStatus(200); // answer first: Meta retries for up to 7 days
enqueue(req.body); // deduplicate on each message id before acting
});Почему нельзя проверить подпись Meta и чем её заменить?
Meta подписывает каждую доставку заголовком X-Hub-Signature-256, HMAC-SHA256 от полезной нагрузки с ключом App Secret принимающего приложения. Для номеров ваших клиентов этим приложением является приложение Tech Provider easyCoexistence, а его секрет не передаётся, поэтому заголовок невозможно проверить на вашей стороне. Вместо него учётными данными служит длинный случайный секрет в пути URL: сравните его за постоянное время и отклоняйте всё остальное. Вторым уровнем защиты внесите в allowlist маршруты, принадлежащие Meta (AS32934), и обновляйте этот список, поскольку Meta периодически меняет IP-адреса.
Какие вебхуки WhatsApp доходят до вашего URL?
Поля, которые альтернативный URL обратного вызова Meta может передавать: messages для того, что присылают клиенты, и статусы того, что отправили вы; smb_message_echoes для того, что бизнес отправляет из приложения WhatsApp Business; а также история и smb_app_state_sync разового импорта. Meta никогда не отправляет вебхуки шаблонов или аккаунта, такие как account_update, на переопределённый адрес. Они поступают на обратный вызов easyCoexistence, поэтому проверку шаблонов читают опросом, а отклонение приходит к вам как событие статуса.
- Адрес назначения задаётся в аккаунте WhatsApp Business, поэтому два номера одного аккаунта используют его совместно: маршрутизируйте по value.metadata.
phone_number_id. - Медиафайлы приходят в виде ID; загрузите файл из Meta с токеном клиента из запроса учётных данных.
- Полезная нагрузка может достигать 3 МБ, поэтому поднимите любой лимит размера тела запроса, установленный ниже этого значения.
Как выглядит пересланное событие соцсети?
POST с Content-Type application/json и заголовком X-EC-Signature, содержащий четыре ключа: platform; account_id, ID канала, который использует Partner API; external_id, ID аккаунта в сети; и entry. Для Instagram и Facebook entry это запись вебхука Meta без изменений, с changes для комментариев и упоминаний и messaging для DM. Для TikTok там лежит событие comment.update с разобранным содержимым и comment_id, video_id и parent_comment_id в виде строк, поэтому 64-битные ID не округляются.
- Аккаунты Instagram подписаны на comments, messages и mentions; страницы Facebook на feed, messages и mention; TikTok отправляет comment.update.
- easyCoexistence не получает событий комментариев от YouTube или LinkedIn: их PUT отвечает 400
not_supported, а комментарии читаются через API каждой сети с учётными данными. - Пересылки не содержат заголовков X-EC-Event или X-EC-Delivery, поэтому дедуплицируйте по собственным ID сети, например по ID комментария или mid сообщения.
{
"platform": "instagram",
"account_id": "<CHANNEL_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793440800,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}Как проверить X-EC-Signature пошагово?
Используйте signing_secret, который вернул PUT /channels/{id}/webhook; он показывается только один раз и уникален для этого аккаунта. Заголовок имеет вид t=<unix>,v1=<hex>. Затем для каждой доставки:
- Прочитайте сырое тело запроса как байты, до любого разбора JSON.
- Разделите заголовок по запятым на t, Unix-время в секундах, и v1, hex-дайджест.
- Отклоните доставку, если t отличается от ваших часов больше чем на 5 минут.
- Вычислите HMAC-SHA256 от t, точки и сырого тела, с ключом секрета этого аккаунта, в виде hex.
- Сравните с v1 за постоянное время, затем ответьте 2xx и поставьте работу в очередь.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database
app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
);
if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
return res.sendStatus(401); // missing or stale timestamp
}
let event;
try {
event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
} catch {
return res.sendStatus(400);
}
const secret = secrets.get(event.account_id);
if (!secret || !sig.v1) return res.sendStatus(401);
const expected = createHmac("sha256", secret)
.update(sig.t + ".")
.update(req.body) // the raw bytes, exactly as they arrived
.digest("hex");
if (expected.length !== sig.v1.length ||
!timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
return res.sendStatus(401);
}
res.sendStatus(204); // one attempt and no retries: acknowledge, then work
enqueue(event);
});Что происходит, когда адрес назначения не задан?
Ничего до вас не доходит, и ничего не ждёт отправки позже. Номер без webhook_url уходит на обратный вызов easyCoexistence, где его сообщения отбрасываются без сохранения, и для него не запускается импорт истории чатов, который запрашивается только при наличии адреса назначения. Аккаунт соцсети без адреса не пересылается: его события всё равно попадают в приложение easyCoexistence, но для вас ни одно не сохраняется. Задайте каждый адрес назначения до того, как понадобится трафик.
Что происходит с адресом назначения, когда подключение разрывается или удаляется?
Номер сохраняет свой адрес назначения. Когда разорвавшийся номер подключается снова, easyCoexistence заново задаёт ваш URL в Meta, то же происходит, когда приостановленный номер возвращается. Удаление аккаунта соцсети очищает его адрес назначения и секрет, поэтому после повторного подключения вызовите PUT /channels/{id}/webhook снова и сохраните новый секрет. Этот PUT выпускает новый секрет всякий раз, когда вызывается с URL, и старый перестаёт подписывать сразу.
Как настроить
- Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
- Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
- Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
- Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.
Распространённые ошибки
- Проверка X-Hub-Signature-256 в доставках WhatsApp ваших клиентов. Meta вычисляет его секретом приложения easyCoexistence, который не передаётся, поэтому проверка не может пройти; аутентифицируйте секретом в пути URL.
- Проверка X-EC-Signature по разобранному JSON. HMAC покрывает сырое тело побайтно, а повторная сериализация меняет байты, поэтому проверяйте до разбора.
- Один секрет для всех каналов. Каждый аккаунт соцсети подписывает своим секретом, а события статусов другим, поэтому ищите секрет по account_id.
- Долгая работа до ответа на пересланное событие. Оно отправляется один раз, ждёт 8 секунд вашего ответа и никогда не повторяется, поэтому сначала ответьте 2xx, а обрабатывайте потом.
easyCoexistence напрямую направляет сообщения каждого номера клиента от Meta на ваш сервер, а комментарии и DM Instagram и Facebook, а также комментарии TikTok пересылает на ваш эндпоинт по мере поступления, подписанными для каждого аккаунта. Копии не хранятся, каждое подключение отслеживается круглосуточно. От US$ 9 за подключение в месяц, до US$ 0,75 по мере добавления подключений, первые 3 дня бесплатно.
Часто задаваемые вопросы
Могу ли я проверить подпись Meta в сообщениях WhatsApp моих клиентов?
Нет. Meta подписывает их секретом приложения Tech Provider easyCoexistence, который не передаётся. Аутентифицируйте длинным случайным секретом в пути вашего URL и, при желании, диапазонами IP-адресов Meta.
Пересылают ли подключения YouTube и LinkedIn события комментариев?
Нет. easyCoexistence не получает событий комментариев от них, поэтому PUT /channels/{id}/webhook отвечает 400 not_supported. Читайте их комментарии через API каждой сети с учётными данными канала.
Повторяются ли пересланные события соцсетей, если мой сервер недоступен?
Нет. Каждое отправляется один раз, копия не сохраняется. Доставки WhatsApp отличаются: Meta сама повторяет их до 7 дней.
Проходят ли сообщения через easyCoexistence?
В WhatsApp нет: Meta доставляет сообщения номера напрямую на заданный вами вебхук. Комментарии и DM из соцсетей пересылаются на ваш эндпоинт по мере поступления, подписанные для каждого аккаунта, без сохранения копии.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на