Верификация вебхука Facebook: hub.challenge и X-Hub-Signature-256
Facebook проверяет эндпоинт вебхука запросом GET, в котором передаются hub.mode со значением subscribe, hub.verify_token и hub.challenge. Эндпоинт сверяет токен с тем, что указан в App Dashboard, и возвращает challenge в теле ответа. Каждое событие затем приходит как POST, подписанное в заголовке X-Hub-Signature-256: sha256= и далее HMAC-SHA256 от тела запроса, с ключом App Secret.
easyCoexistence берёт на себя сторону Meta для каждой подключаемой Страницы: его приложение отвечает на hub.challenge, проверяет X-Hub-Signature-256, подписывает Страницу на feed, messages и mention, затем пересылает события на ваш HTTPS-эндпоинт, подписанные через X-EC-Signature и секрет для этой Страницы.
Значение hub.mode всегда передаётся в запросе верификации Meta; hub.challenge это целое число, которое нужно вернуть.
Префикс X-Hub-Signature-256, за которым следует подпись SHA256, которую Meta формирует из тела запроса и App Secret.
Как быстро эндпоинт вебхука Messenger должен отвечать 200 OK на каждое уведомление.
Число неудачных доставок, после которого появляется оповещение Webhooks Disabled и приложение отписывается от Страницы.
Как долго Meta повторяет неудачную доставку уведомления Страницы, с убывающей частотой, прежде чем отбросить его.
Что содержит запрос верификации Meta?
GET-запрос на URL обратного вызова. Отправляется всякий раз, когда продукт Webhooks настроен в App Dashboard или подписка создана через /{app-id}/subscriptions. С ним передаются три параметра строки запроса:
- hub.mode: всегда subscribe.
- hub.challenge: целое число, которое эндпоинт должен вернуть.
- hub.
verify_token: строка, введённая в поле «Verify Token» в App Dashboard. - PHP заменяет точки на подчёркивания, поэтому они читаются как
hub_mode,hub_challengeиhub_verify_token.
Как эндпоинт должен на него отвечать?
Ответом 200, всё тело которого это значение hub.challenge, но только если hub.mode равен subscribe и hub.verify_token совпадает. Во всех остальных случаях возвращается 403, как в примере приложения Meta. App Dashboard показывает, прошёл ли эндпоинт проверку, а /{app-id}/subscriptions отвечает успехом или ошибкой. Эндпоинт должен работать по HTTPS с действительным сертификатом TLS или SSL, так как самоподписанные сертификаты не поддерживаются.
Как вычисляется X-Hub-Signature-256?
Это HMAC-SHA256 от тела запроса, ключом служит App Secret приложения. Результат записывается в нижнем регистре в шестнадцатеричном виде после sha256=. Руководство Meta по Messenger добавляет, что подпись покрывает тело с экранированными Unicode-символами, поэтому строка вида äöå учитывается как \u00e4\u00f6\u00e5. Хешируйте исходное тело в том виде, в котором оно пришло, а не декодированную или повторно сериализованную копию. Meta говорит, что проверка необязательна, но настоятельно рекомендует её делать.
Как это проверить в коде?
Сохраните сырые байты, вычислите HMAC, сравните за постоянное время, затем разбирайте. Функция get_data во Flask возвращает тело без изменений, а именно по нему вычислялась подпись. Если сначала разобрать тело, а затем сериализовать его заново, байты изменятся. Небольшой эндпоинт, который отвечает на верификацию и проверяет каждый POST:
import hashlib, hmac, os
from flask import Flask, abort, request
app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()
@app.get("/webhooks/facebook")
def verify():
token = request.args.get("hub.verify_token", "")
if request.args.get("hub.mode") == "subscribe" and hmac.compare_digest(token.encode(), VERIFY_TOKEN.encode()):
return request.args.get("hub.challenge", ""), 200
abort(403)
@app.post("/webhooks/facebook")
def receive():
raw = request.get_data() # the bytes Meta signed
expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected.encode(), request.headers.get("X-Hub-Signature-256", "").encode()):
abort(401)
# answer at once; hand request.get_json() to a queue for the work
return "EVENT_RECEIVED", 200Чего Meta ждёт после верификации?
Ответа 200 OK на каждое уведомление, в течение 5 секунд для событий Messenger. Meta объединяет до 1 000 обновлений в одну доставку, но этого не гарантирует, и сбои обрабатывает так:
- Уведомления о Страницах: повторяются сразу, затем ещё несколько раз с убывающей частотой в течение 36 часов, после чего отбрасываются.
- Уведомления Messenger: несколько повторов сразу. После 15 минут сбоев оповещение приходит на аккаунт разработчика.
- Через час сбоев приходит оповещение Webhooks Disabled, и приложение отписывается от Страницы до новой подписки.
- Повторы могут доставить событие дважды и не по порядку, поэтому удаляйте дубликаты и сортируйте сообщения по метке времени.
- Прошлые уведомления нельзя запросить позже, поэтому сохраняйте нужное по мере поступления.
Как easyCoexistence проходит проверки Meta?
Его приложение Meta имеет один URL обратного вызова для подключаемых Страниц, и этот эндпоинт выполняет обе проверки сам. Он отвечает на GET только тогда, когда hub.mode равен subscribe и токен верификации совпадает, сравнение выполняется за постоянное время. В остальных случаях возвращается 403. Каждый POST он читает как сырой текст, пересчитывает X-Hub-Signature-256 со своим App Secret, отклоняет несовпадение ответом 401 и сразу отвечает Meta, обрабатывая событие после ответа.
Как easyCoexistence подписывает пересылаемые данные?
Собственной подписью, так как заголовок Meta можно проверить только App Secret easyCoexistence, и он не передаётся дальше. Каждая запись для подключённой Страницы с заданным эндпоинтом отправляется туда POST-запросом в формате JSON: {platform, account_id, external_id, entry}. Заголовок X-EC-Signature имеет вид t=<unix>,v1=<hex>, где v1 это HMAC-SHA256 от метки времени, точки и сырого тела, с ключом подписи этой Страницы:
- Секрет начинается с whsec_ и показывается один раз: его выдают
set_social_webhook_destinationили PUT /channels/:id/webhook в Partner API. - Повторная установка URL выпускает новый секрет, а URL со значением null выключает пересылку.
- Каждая пересылка отправляется однократно, с ожиданием до 8 секунд, без следования редиректам, на адрес HTTPS, который разрешается в публичный IP.
- Копия события не хранится, поэтому повторять нечего.
Как проверить X-EC-Signature?
Разделите заголовок на t и v1, отклоните метку времени старше 5 минут, пересчитайте HMAC от t, точки и сырого тела с секретом подписи Страницы и сравните за постоянное время. В Node.js, при сохранении тела в виде сырых байтов:
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.EC_SIGNING_SECRET; // whsec_..., shown once
app.post("/events/facebook", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
String(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("="))
);
const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
const expected = crypto
.createHmac("sha256", SECRET)
.update(Buffer.concat([Buffer.from(`${sig.t}.`), req.body]))
.digest("hex");
const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
if (!ok) return res.sendStatus(401);
res.sendStatus(200); // answer first: forwards are not retried
const { platform, account_id, external_id, entry } = JSON.parse(req.body.toString("utf8"));
// queue entry for the work
});Распространённые ошибки
- Оборачивать hub.challenge в JSON или кавычки. Тело ответа 200 должно быть самим значением challenge.
- Вычислять HMAC после JSON-парсера. Разбор и повторная сериализация меняют байты, а Meta подписывает тело с экранированным Unicode, поэтому хешируйте сырое тело.
- Выполнять работу до ответа. Messenger ждёт 200 в течение 5 секунд, а час сбоев отписывает приложение от Страницы.
- Проверять подпись Meta в пересланных событиях. Meta подписывает App Secret easyCoexistence, а пересланное событие несёт X-EC-Signature, который проверяется секретом подписи Страницы.
От US$ 9 до US$ 0,75 за подключение в месяц, с понижением по мере добавления подключений, первые 3 дня бесплатно.
Часто задаваемые вопросы
Откуда берётся токен верификации?
Его задаёт сам разработчик. Это строка, которая вводится в поле «Verify Token» при настройке вебхуков в App Dashboard, или verify_token, отправляемый в /{app-id}/subscriptions.
Можно ли проверить верификацию через curl?
Да. Руководство Meta по Messenger отправляет GET с hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED и hub.mode=subscribe, и рабочий эндпоинт отвечает CHALLENGE_ACCEPTED.
Что будет, если эндпоинт выходит из строя на час?
Meta отправляет оповещение Webhooks Disabled и отписывает приложение от Страницы. После исправления эндпоинта подпишите Страницу заново через subscribed_apps.
Нужно ли иметь собственное приложение Meta, чтобы получать вебхуки Страницы?
С easyCoexistence не нужно. Meta доставляет события своему приложению, которое пересылает события каждой Страницы на указанный вами эндпоинт, подписанные через X-EC-Signature.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на