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

События вебхука Instagram: комментарии, упоминания и личные сообщения (DM)

События вебхука Instagram сообщают о действиях на профессиональном аккаунте по мере их появления: новых комментариях, @-упоминаниях и DM. Meta отправляет каждое событие POST-запросом в формате JSON на HTTPS-эндпоинт подключённого приложения и повторяет неудачную доставку на него в течение до 36 часов. easyCoexistence передаёт каждое событие вашему эндпоинту один раз, подписанным для каждого аккаунта, без повторных попыток. При входе через Instagram Login упоминания приходят внутри уведомления о комментариях.

36 hours

Как долго Meta повторяет неудачную доставку на эндпоинт приложения, прежде чем отбросить её.

1,000

Большинство обновлений Meta объединяет в одну доставку вебхука, хотя группировку не гарантирует.

is_echo

Флаг, который Meta выставляет для событий сообщений, отправленных самим аккаунтом.

Public

Уведомления о комментариях и упоминаниях вызывают только медиа публичных аккаунтов.

Какие бывают события?

Для профессионального аккаунта, подключённого через 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. Новый комментарий выглядит так:

A forwarded comment event
{
  "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 минут.

Node.js: verifying X-EC-Signature
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

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 включает упоминания в уведомление о комментариях, поэтому они приходят по тому же пути, что и комментарии.

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

Модерация комментариев в Instagram через APIКак API Instagram читает комментарии, отвечает на них, скрывает и удаляет: публичные ответы, один личный ответ на комментарий в течение 7 дней и правила.Instagram DM через API и 24-часовое окноКак работают личные сообщения Instagram через API: кому может писать аккаунт, окно 24 часа, приватные ответы и настройка «Allow access to messages».Ошибки Instagram API: что означают распространённые кодыЧастые ошибки Instagram API: истёкшие токены, лимиты частоты, медиа, которые Meta не может загрузить, дневной лимит публикаций, закрытые окна переписки.Какие аккаунты Instagram работают с API: бизнес, креатор или личныйAPI Instagram работает с профессиональными аккаунтами: бизнес и креатор. Какой выбрать, что меняется при переходе и как переключиться в приложении.Вебхук комментариев Instagram: полезная нагрузка поле за полемЧто вебхук комментариев Instagram присылает при комментарии к постам и Reels аккаунта: поля полезной нагрузки, чего в ней нет и ловушки.Вебхук сообщений Instagram: тело DM, эхо и поляЧто вебхук сообщений Instagram передаёт для DM: IGSID отправителя, текст, вложения, ответы на сторис и эхо, поле за полем, и окно 24 часа.

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

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

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

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