ВойтиНачать бесплатный пробный период
easyCoexistence Официальные API

Верификация вебхука 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 и секрет для этой Страницы.

subscribe

Значение hub.mode всегда передаётся в запросе верификации Meta; hub.challenge это целое число, которое нужно вернуть.

sha256=

Префикс X-Hub-Signature-256, за которым следует подпись SHA256, которую Meta формирует из тела запроса и App Secret.

5 seconds

Как быстро эндпоинт вебхука Messenger должен отвечать 200 OK на каждое уведомление.

1 hour

Число неудачных доставок, после которого появляется оповещение Webhooks Disabled и приложение отписывается от Страницы.

36 hours

Как долго 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:

Python: hub.challenge and X-Hub-Signature-256
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, при сохранении тела в виде сырых байтов:

Node.js: checking X-EC-Signature on a forwarded event
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, который проверяется секретом подписи Страницы.
Настройка с EasyCoexistence

От 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.

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

Подписка страницы Facebook на вебхуки: эндпоинт subscribed_appsКак POST /{page-id}/subscribed_apps подписывает страницу Facebook на поля вебхука: токены, задачи, подписка приложения, проверка и удаление.Поля вебхука Страницы Facebook: полный списокMeta документирует 64 поля вебхука Страницы Facebook: feed, mention, поля Messenger вроде messages и поля профиля, а также нужное разрешение.Вебхук Messenger для Facebook Page: сообщения и упоминанияПоля вебхука Facebook Page для сообщений Messenger и упоминаний: формат тела запроса, ID отправителей, вложения и доставка событий на ваш эндпоинт.Вебхук ленты Facebook Страницы: события комментариев, публикаций и реакцийЧто передаёт вебхук ленты Facebook Страницы при комментариях, публикациях и реакциях: поля item и verb, структура тела запроса Meta и подписка Страницы.Токен доступа к странице Facebook: как долго он действует и что его аннулируетКак получить токен доступа к странице Facebook без срока действия, кто может его получить и что заставляет Meta перестать его принимать.

Подключите первый канал за две минуты.

Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.

  • 3 дня бесплатно
  • Отмена в любой момент
  • Только официальные API
  • Мониторинг 24/7

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