События вебхука Instagram: комментарии, упоминания и личные сообщения (DM)
События вебхука Instagram сообщают о действиях на профессиональном аккаунте по мере их появления: новых комментариях, @-упоминаниях и DM. Meta отправляет каждое событие POST-запросом в формате JSON на HTTPS-эндпоинт подключённого приложения и повторяет неудачную доставку на него в течение до 36 часов. easyCoexistence передаёт каждое событие вашему эндпоинту один раз, подписанным для каждого аккаунта, без повторных попыток. При входе через Instagram Login упоминания приходят внутри уведомления о комментариях.
Как долго Meta повторяет неудачную доставку на эндпоинт приложения, прежде чем отбросить её.
Большинство обновлений Meta объединяет в одну доставку вебхука, хотя группировку не гарантирует.
Флаг, который Meta выставляет для событий сообщений, отправленных самим аккаунтом.
Уведомления о комментариях и упоминаниях вызывают только медиа публичных аккаунтов.
Какие бывают события?
Для профессионального аккаунта, подключённого через Instagram Login, в виде событий приходят три вида активности:
- Комментарии: новый комментарий к медиа аккаунта, с ID комментария, Instagram-scoped ID и именем пользователя автора, текстом, а также ID и типом медиа.
- Упоминания: при Instagram Login приходят внутри уведомления о комментариях, а не отдельным полем.
- Сообщения: DM на аккаунт с отправителем, получателем, временной меткой и самим сообщением, включая текст, вложения и ответы на Stories.
Как события доходят до вашего эндпоинта?
Meta доставляет вебхуки Instagram приложению, к которому подключён аккаунт. easyCoexistence принимает их и передаёт каждое на HTTPS-эндпоинт, заданный вами для этого аккаунта, сразу по мере поступления, подписанным секретным ключом этого аккаунта.
Задайте эндпоинт через set_social_webhook_destination из Claude или ChatGPT либо через Partner API командой PUT /channels/:id/webhook. Секрет подписи показывается один раз; повторная настройка эндпоинта выпускает новый, а передача null вместо URL отключает пересылку.
Как выглядит доставка?
POST-запрос с JSON-телом, содержащим platform, account_id, который возвращает list_social_accounts для подключения, external_id аккаунта Instagram и entry: запись вебхука Meta для события, без изменений. DM приходит так же, только вместо changes используется массив messaging. Новый комментарий выглядит так:
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793318400,
"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 в виде t=<unix>,v1=<hex>, где v1 является HMAC-SHA256 от метки времени, точки и исходного тела запроса, с ключом секрета аккаунта. Вычислите подпись по исходному телу ровно в том виде, в каком оно пришло, сравните её за постоянное время и отклоняйте метку времени старше 5 минут.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}Повторяется ли доставка?
easyCoexistence не повторяет: пересылка передаёт каждое событие один раз, в памяти, и не хранит копию для повтора. Отвечайте 2xx быстро, работу выполняйте после, а нужное сохраняйте в момент получения, так как Meta тоже не ведёт историю прошлых уведомлений, которую можно запросить.
Сама Meta повторяет неудачную доставку на приложение до 36 часов, поэтому одно и то же событие может изредка прийти дважды: опирайтесь на ID комментария или mid сообщения при дедупликации.
Что ещё проверить в обработчике?
Несколько деталей в телах событий Meta, на которых спотыкается первый обработчик:
is_echo: событие сообщения сis_echo, равным true, отправлено самим аккаунтом, поэтому ответа не требует.- Ответы на Stories: DM-ответ на Story содержит
reply_toс ID и URL Story. - Упоминания в Stories: приходят как сообщение, у которого тип вложения
story_mention. - time: момент, когда Meta отправила уведомление, а не когда создан комментарий или сообщение; время самого сообщения находится в его записи messaging.
- ID альбомов: события комментариев их не содержат; найдите альбом по ID комментария.
Распространённые ошибки
- Выполнять работу до ответа. Пересылка не повторяет, поэтому сразу возвращайте 2xx и обрабатывайте событие после.
- Проверять подпись по разобранному JSON. Вычисляйте HMAC по исходному телу ровно в том виде, в каком оно пришло.
- Отвечать на эхо. Событие сообщения с is_echo отправлено самим аккаунтом, и ответ на него запускает цикл.
- Пропускать дедупликацию. Meta может повторно доставить то же событие после сбоя, поэтому опирайтесь на ID комментария или mid сообщения.
easyCoexistence пересылает комментарии, упоминания и DM аккаунта Instagram на ваш HTTPS-эндпоинт по мере поступления, подписанными секретным ключом аккаунта и без копии по пути. Включите через set_social_webhook_destination из Claude или ChatGPT либо через Partner API. От US$ 9 до US$ 0,75 за подключение в месяц, снижаясь по мере добавления подключений, первые 3 дня бесплатно.
Часто задаваемые вопросы
Что означает поле time в вебхуке Instagram?
Момент, когда Meta отправила уведомление, а не когда создан комментарий или сообщение. Собственное время DM находится в его записи messaging.
Повторяет ли Meta неудачные доставки вебхуков Instagram?
Да. Meta повторяет неудачную доставку на приложение до 36 часов, поэтому одно и то же событие может изредка прийти дважды: дедуплицируйте по ID комментария или mid сообщения. easyCoexistence передаёт каждое событие на ваш эндпоинт один раз, поэтому отвечайте 2xx быстро.
Сколько обновлений может содержать одна доставка вебхука Instagram?
До 1 000, когда Meta их объединяет, хотя группировку Meta не гарантирует. Перебирайте весь массив entry, а не только первый элемент.
Есть ли у упоминаний собственное событие?
При Instagram Login нет. Meta включает упоминания в уведомление о комментариях, поэтому они приходят по тому же пути, что и комментарии.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на