Как работает вебхук Instagram
Вебхук Meta состоит из двух этапов: подтверждение адреса (GET) и доставка событий (POST). Каждый POST-запрос приходит с подписью HMAC-SHA256 в заголовке X-Hub-Signature-256, и считается она по сырому телу. Чтобы события Instagram вообще приходили, приложение должно быть в режиме Live, аккаунт подписан через subscribed_apps, а для комментариев получен Advanced Access.
Опубликовано: Обновлено:
Коротко: как идёт поток
Вы указываете callback URL и verify token в App Dashboard. Meta присылает GET-запрос: если hub.mode=subscribe и hub.verify_token совпадает, возвращаете ровно значение hub.challenge. Затем события приходят POST-запросами (до 1000 в пакете): проверяете подпись, разбираете события, делаете дедупликацию и сразу возвращаете 200.
Проверка подписи
Это стандартная проверка на уровне платформы — логика та же и без SDK.
import hmac, hashlib
def verify(raw_body: bytes, header: str, app_secret: str) -> bool:
if not header or not header.startswith("sha256="):
return False
expected = hmac.new(app_secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header.split("=", 1)[1])raw_body обязан быть сырыми байтами от фреймворка. Повторно сериализованный JSON ломает подпись.
В Socialift SDK та же логика — функция verify_request(app_secret, body, headers), а GET-проверка — verify_challenge.
Почему одно событие приходит дважды
Meta доставляет события по принципу «хотя бы один раз». Если ваш endpoint отвечает медленно или возвращает ошибку, доставка повторяется — и одно событие может дойти дважды.
ID события Meta не передаёт, поэтому правильное решение — строить стабильный ключ из содержимого (mid для сообщения, leadgen_id для лида, comment_id для комментария) и отбрасывать повторы. Иначе в CRM появятся дублирующиеся сделки или лиды. В SDK это dedupe_key().
Второе правило — быстро возвращать 200. Тяжёлую обработку (запись в CRM, отправку уведомлений) нужно уносить в очередь.
Чек-лист для продакшена
- Запросы с неверной подписью отклоняйте с 401/403 и пишите в лог.
- Meta не даёт ID события: стройте ключ из содержимого (mid для сообщения, leadgen_id для лида, comment_id для комментария) и храните его с временем доставки в уникальном столбце.
- Даже без очереди не блокируйте ответ на доставку.
- Держите verify_token и app_secret в переменных окружения.
- Нужен действительный TLS-сертификат — самоподписанные не поддерживаются.
- Приложение должно быть в режиме Live — иначе вебхуки Instagram не приходят.
- Для событий comments и live_comments нужен Advanced Access; события о комментариях и @упоминаниях приходят только для публичных аккаунтов.
- Подпишите аккаунт: POST /me/subscribed_apps с subscribed_fields=messages,comments,... (при Facebook Login — токеном страницы).
Частые вопросы
Подпись вебхука никогда не совпадает, что делать?
Сначала убедитесь, что используете сырое тело — многие фреймворки парсят его автоматически. Затем проверьте корректность app secret и что промежуточный прокси не изменяет тело.
Можно ли использовать опрос вместо вебхука?
Как резервный механизм — да. Как основной поток — нет: опрос быстро расходует лимиты и увеличивает время реакции.
Сколько раз Meta повторяет доставку?
Meta повторяет неудачную доставку сразу, затем всё реже в течение 36 часов; через 36 часов неподтверждённые события отбрасываются. Поэтому быстро возвращайте 200 и делайте дедупликацию.
Почему не приходит вебхук Instagram?
Самые частые причины: приложение не в режиме Live, аккаунт не подписан через /me/subscribed_apps, нет Advanced Access для комментариев или аккаунт закрытый. Если endpoint использует самоподписанный сертификат, Meta тоже не доставит событие.
Сколько событий приходит в одном запросе?
Meta отправляет события пакетами: в одном POST может быть до 1000 изменений. Поэтому полностью обходите массивы changes и messaging внутри entry — в Socialift SDK parse_events() превращает каждое в отдельный WebhookEvent.