Верификация вебхуков Instagram: hub.challenge и X-Hub-Signature-256
Для вебхуков Instagram нужен эндпоинт HTTPS, который отвечает на GET-запрос верификации от Meta. Этот запрос содержит hub.mode со значением subscribe, hub.verify_token и hub.challenge. Эндпоинт проверяет токен и возвращает hub.challenge. Затем Meta отправляет POST-запросы с событиями в JSON, подписанные заголовком X-Hub-Signature-256 с секретом приложения, после того как приложение подпишется на поля и каждый аккаунт подпишется через edge subscribed_apps.
easyCoexistence занимается стороной Meta: его приложение проходит верификацию, проверяет X-Hub-Signature-256, подписывает каждый подключённый аккаунт Instagram на comments, messages и mentions и пересылает события на ваш эндпоинт HTTPS, подписанные X-EC-Signature и секретом для каждого аккаунта, при этом круглосуточно следит за каждым подключением.
Значение hub.mode всегда присутствует в запросе верификации Meta.
Период, в течение которого Meta повторяет неудачное уведомление с убывающей частотой, прежде чем отбросить его.
Количество неудачных доставок сообщений, после которого Meta отправляет оповещение в аккаунт разработчика.
Количество неудачных доставок сообщений, после которого появляется оповещение Webhooks Disabled, а приложение отписывается от аккаунта.
Режим Live, который Meta требует, прежде чем приложение начнёт получать уведомления для аккаунтов своих пользователей.
Как работает настройка вебхуков Instagram?
Настройка идёт в четыре шага, в том порядке, в каком их приводит руководство Meta. Эндпоинт должен пройти верификацию до того, как можно будет выбрать любое поле. Чтобы получать уведомления для аккаунтов пользователей, приложение должно быть в режиме Live, а для рабочего доступа нужна верификация бизнеса.
Что содержит запрос верификации?
GET-запрос на URL обратного вызова, который отправляется каждый раз, когда продукт Webhooks настроен в App Dashboard. Если hub.verify_token совпадает с токеном самого эндпоинта, ответ: статус 200 и значение hub.challenge как всё тело ответа. Иначе ответ 403. App Dashboard показывает, прошёл ли эндпоинт проверку.
- hub.mode: всегда subscribe.
- hub.challenge: целое число, которое генерирует Meta и которое эндпоинт обязан вернуть.
- hub.
verify_token: строка, введённая в поле Verify Token в панели, которую должны знать только Meta и эндпоинт. - В PHP точки в этих именах заменяются на подчёркивания, поэтому значения приходят как
hub_mode,hub_challengeиhub_verify_token.
GET https://<YOUR_HOST>/webhooks/instagram
?hub.mode=subscribe
&hub.challenge=1158201444
&hub.verify_token=<YOUR_VERIFY_TOKEN>
HTTP/1.1 200 OK
Content-Type: text/plain
1158201444Где задаются URL обратного вызова и поля?
В App Dashboard, в разделе Instagram, «API setup with Instagram login», «Configure webhooks»: там указываются URL обратного вызова и verify token, а после сохранения запускается запрос верификации. Продукт Instagram изначально подписан на comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral и messaging_seen, а «Manage» позволяет отписаться от любого из них. Кнопка Test отправляет тестовое уведомление для выбранного поля.
Как проверяется X-Hub-Signature-256?
Meta подписывает каждое уведомление HMAC-SHA256 от тела запроса, ключом служит секрет приложения. Подпись передаётся в заголовке X-Hub-Signature-256 в виде sha256= и hex-дайджеста. Получатель вычисляет тот же HMAC по исходному телу запроса и сравнивает его с заголовком за постоянное время. В руководстве Meta по сообщениям указано, что подпись охватывает тело с экранированным Unicode, поэтому хеш декодированного или повторно сериализованного JSON будет другим.
import crypto from "node:crypto";
import express from "express";
const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;
// Verification request: send hub.challenge back when the token matches
app.get("/webhooks/instagram", (req, res) => {
const ok = req.query["hub.mode"] === "subscribe" &&
req.query["hub.verify_token"] === VERIFY_TOKEN;
if (!ok) return res.sendStatus(403);
res.status(200).type("text/plain").send(req.query["hub.challenge"]);
});
// Event notification: check the signature over the raw bytes
app.post("/webhooks/instagram", express.raw({ type: "application/json" }), (req, res) => {
const expected = Buffer.from(
"sha256=" + crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex")
);
const given = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
return res.sendStatus(401);
}
res.sendStatus(200); // answer first, work after
const body = JSON.parse(req.body.toString("utf8"));
// hand body.entry to a queue or background job
});
app.listen(3000);Почему проверить подпись может только секрет приложения?
Потому что подпись представляет собой HMAC, ключом которого служит секрет приложения. Без него никто не может вычислить ожидаемое значение, а тот, у кого есть копия тела, не может подделать его. Поэтому проверка должна выполняться на сервере, который получает запросы Meta для приложения. Meta просит, чтобы секреты приложения, токены доступа и учётные данные клиента не попадали в логи и обращения в поддержку. Система, которая получает события, переданные другим приложением, не может проверить подпись Meta вообще и опирается на собственную подпись того приложения.
Зачем каждому аккаунту нужна своя подписка?
Потому что App Dashboard задаёт, что приложение может получать, но уведомления по аккаунту начинают приходить только после того, как этот аккаунт тоже подписан. При Instagram Login отправьте POST /<IG_ID>/subscribed_apps на graph.instagram.com с токеном доступа пользователя Instagram для этого аккаунта и subscribed_fields со списком полей, выбранных для приложения, через запятую. Успешный вызов возвращает success со значением true.
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }Что делает Meta, когда доставка не удаётся?
Meta повторяет попытку, а затем отказывается. Руководство Meta требует ответа 200 OK на каждое уведомление и предупреждает, что пакетная отправка до 1 000 обновлений не гарантирована. Неудачное обновление повторяется сразу, затем ещё несколько раз с убывающей частотой в течение 36 часов, после чего отбрасывается, поэтому одно и то же событие может прийти дважды. События сообщений подчиняются правилам доставки сообщений Meta, которые действуют быстрее:
- Ожидается ответ 200 OK в течение 5 секунд, а при неудачной доставке делается несколько немедленных повторов, поэтому дедуплицируйте по mid сообщения.
- После 15 минут сбоев оповещение уходит в аккаунт разработчика.
- После часа сбоев появляется оповещение Webhooks Disabled, и приложение отписывается от вебхуков аккаунта, пока не подпишется снова.
- Сообщения, отправленные во время сбоя, могут прийти не по порядку, поэтому отсортируйте их по timestamp.
Что проверить, если ничего не приходит?
Чек-лист поиска неполадок Meta, который охватывает большинство молчащих эндпоинтов, в таком порядке:
- URL обратного вызова прошёл проверку и доступен по HTTPS с действительным сертификатом. Самоподписанные сертификаты не поддерживаются.
- Приложение выбрало поле и имеет нужный уровень доступа: Advanced Access для comments и
live_comments. - Уведомления включены для аккаунта через
subscribed_apps, с токеном из той же настройки входа. - Аккаунт соответствует правилам поля: для уведомлений о комментариях нужны медиа, принадлежащие публичному аккаунту.
- Сервер отвечает success до начала медленной обработки.
Зачем easyCoexistence подписывает пересылаемые события повторно?
Потому что подпись Meta не может передаваться дальше. Приложение easyCoexistence получает доставку Meta, проверяет X-Hub-Signature-256 собственным секретом приложения, сразу отвечает Meta и отправляет каждую запись для подключённого аккаунта на эндпоинт, заданный для этого аккаунта, внутри нового тела с полями platform, account_id, external_id и entry. Заголовок Meta не передаётся дальше, а без секрета проверить его было бы нельзя, поэтому каждая пересылка несёт Content-Type: application/json и X-EC-Signature, подписанный ключом, который принадлежит только этому аккаунту.
Как проверить X-EC-Signature?
Заголовок имеет вид t=<unix>,v1=<hex>, где v1 представляет собой hex HMAC-SHA256 от метки времени, точки и исходного тела, с ключом в виде секрета подписи аккаунта. Пересчитайте его по байтам ровно в том виде, в каком они пришли, сравните за постоянное время и отклоните метку времени старше 5 минут.
- Секрет начинается с whsec_ и показывается один раз: его возвращают
set_social_webhook_destinationили PUT /channels/:id/webhook при задании URL. - Повторная установка URL выпускает новый секрет, а значение null для URL отключает пересылку.
- Каждое событие отправляется один раз, с ожиданием до 8 секунд, без следования редиректам, на адрес HTTPS, который разрешается в публичный IP.
- Удаление подключения отписывает аккаунт от вебхуков Meta и очищает его эндпоинт и секрет.
import hashlib, hmac, time
def verify_ec_signature(raw_body: bytes, header: str, secret: str) -> bool:
"""Check X-EC-Signature on an event forwarded by easyCoexistence."""
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, malformed or older than 5 minutes
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), v1.encode())Распространённые ошибки
- Возврат challenge в JSON или в кавычках. Meta ожидает значение hub.challenge как само тело ответа, со статусом 200.
- Хеширование разобранного тела. Парсер JSON отбрасывает точные байты, которые подписала Meta, поэтому сохраняйте сырое тело для HMAC и разбирайте его после.
- Подписка приложения без аккаунта. Пока POST /<IG_ID>/subscribed_apps не выполнен успешно для аккаунта, уведомления по нему не приходят.
- Сбой эндпоинта на целый час. Meta отключает вебхуки сообщений и отписывает приложение от аккаунта, после чего его нужно подписать заново.
Включается через set_social_webhook_destination или Partner API. Цена: от US$ 9 до US$ 0,75 за подключение в месяц, по мере добавления подключений стоимость снижается. Пробный период: первые 3 дня бесплатно.
Часто задаваемые вопросы
Что такое hub.challenge в вебхуках Instagram?
Целое число, которое Meta отправляет в GET-запросе верификации. После проверки hub.verify_token эндпоинт возвращает его как тело ответа, что подтверждает контроль над URL.
Почему в PHP нет hub.mode и hub.challenge?
PHP заменяет точки в именах параметров на подчёркивания, поэтому значения верификации Meta приходят как hub_mode, hub_challenge и hub_verify_token.
Как снова включить вебхуки Instagram после отключения Meta?
Исправьте эндпоинт, затем подпишите аккаунт заново через POST /<IG_ID>/subscribed_apps с теми же полями.
Подходит ли самоподписанный сертификат для эндпоинта вебхука Instagram?
Нет, Meta не поддерживает самоподписанные сертификаты: URL обратного вызова должен быть доступен по HTTPS с действительным сертификатом. Это первый пункт в чек-листе поиска неполадок Meta.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на