Zaloguj sięRozpocznij bezpłatny okres próbny
easyCoexistence Oficjalne API

Zdarzenia webhook z Instagrama: komentarze, wzmianki i wiadomości DM

Zdarzenia webhook z Instagrama informują na bieżąco o aktywności na koncie profesjonalnym: nowych komentarzach, wzmiankach @ i wiadomościach DM. Meta wysyła każde z nich metodą POST jako JSON na endpoint HTTPS połączonej aplikacji i ponawia nieudaną dostawę do tego endpointu przez maksymalnie 36 godzin. easyCoexistence przekazuje każde zdarzenie do Twojego endpointu jednorazowo, podpisane osobno dla każdego konta, bez ponawiania. Przy Instagram Login wzmianki przychodzą w powiadomieniu o komentarzach.

36 hours

Jak długo Meta ponawia nieudaną dostawę do endpointu aplikacji, zanim ją porzuci.

1,000

Większość aktualizacji Meta grupuje w jedną dostawę webhooka, choć nie gwarantuje grupowania.

is_echo

Znacznik, który Meta ustawia przy zdarzeniach wiadomości wysłanych przez samo konto.

Public

Tylko media na kontach publicznych wyzwalają powiadomienia o komentarzach i wzmiankach.

Jakie są zdarzenia?

Dla konta profesjonalnego połączonego przez Instagram Login jako zdarzenia przychodzą trzy rodzaje aktywności:

  • Komentarze: nowy komentarz pod mediami konta, z identyfikatorem komentarza, identyfikatorem autora w zakresie Instagrama oraz jego nazwą użytkownika, tekstem, identyfikatorem mediów i ich typem.
  • Wzmianki: przy Instagram Login trafiają w powiadomieniu o komentarzach, a nie jako osobne pole.
  • Wiadomości: DM do konta, z nadawcą, odbiorcą, znacznikiem czasu i samą wiadomością, w tym tekstem, załącznikami i odpowiedziami na relacje.

Jak zdarzenia docierają do endpointu?

Meta dostarcza webhooki Instagrama do aplikacji, którą konto połączyło. easyCoexistence odbiera je i przekazuje każde do endpointu HTTPS, który ustawiłeś dla tego konta, w chwili nadejścia, podpisane sekretem przypisanym do tego konta.

Endpoint ustawisz narzędziem set_social_webhook_destination z Claude lub ChatGPT albo przez Partner API, wywołując PUT /channels/:id/webhook. Sekret podpisu pokazywany jest tylko raz, ponowne ustawienie endpointu wystawia nowy, a podanie null jako URL wyłącza przekazywanie.

Jak wygląda dostawa?

Żądanie POST z treścią w formacie JSON, zawierające platformę, account_id, który list_social_accounts zwraca dla połączenia, external_id konta Instagrama oraz entry: wpis webhooka Meta dla zdarzenia, bez zmian. DM przychodzi w ten sam sposób, z tablicą messaging zamiast changes. Nowy komentarz wygląda tak:

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>" }
        }
      }
    ]
  }
}

Jak zweryfikować dostawę?

Każda dostawa niesie nagłówek X-EC-Signature w postaci t=<unix>,v1=<hex>, gdzie v1 to HMAC-SHA256 znacznika czasu, kropki i surowej treści żądania, z kluczem będącym sekretem podpisu konta. Oblicz go na surowej treści dokładnie tak, jak została odebrana, porównaj w stałym czasie i odrzuć znacznik czasu starszy niż 5 minut.

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));
}

Czy dostawa jest ponawiana?

Nie przez easyCoexistence: przekazuje ono każde zdarzenie jednorazowo, w pamięci, i nie zachowuje kopii, z której mogłoby ponowić dostawę. Odpowiedz szybko kodem 2xx, a pracę wykonaj później, i zapisz to, czego potrzebujesz, w chwili odbioru, ponieważ Meta również nie prowadzi historii minionych powiadomień, którą można by odpytać.

Sama Meta ponawia nieudaną dostawę do aplikacji przez maksymalnie 36 godzin, więc to samo zdarzenie może sporadycznie dotrzeć dwa razy: deduplikuj je po identyfikatorze komentarza lub mid wiadomości.

Co jeszcze powinna sprawdzać obsługa zdarzeń?

Kilka szczegółów w payloadach Meta, które zaskakują pierwszą implementację:

  • is_echo: zdarzenie wiadomości z is_echo ustawionym na true zostało wysłane przez samo konto, więc nie wymaga odpowiedzi.
  • Odpowiedzi na relacje: DM odpowiadający na relację zawiera reply_to z identyfikatorem i adresem URL relacji.
  • Wzmianki w relacjach: przychodzą jako wiadomość, której typ załącznika to story_mention.
  • time: moment wysłania powiadomienia przez Meta, a nie chwila utworzenia komentarza lub wiadomości; własny znacznik czasu wiadomości znajduje się w jej wpisie messaging.
  • Identyfikatory albumów: zdarzenia komentarzy ich nie zawierają; wyszukaj album po identyfikatorze komentarza.

Typowe błędy

  • Wykonywanie pracy przed odpowiedzią. Przekazywanie nie ponawia dostaw, więc zwróć kod 2xx od razu i przetwórz zdarzenie później.
  • Weryfikacja podpisu na sparsowanym JSON. Oblicz HMAC na surowej treści dokładnie tak, jak przyszła.
  • Odpowiadanie na echa. Zdarzenie wiadomości z is_echo ustawionym na true zostało wysłane przez konto, a odpowiedź na nie zapoczątkuje pętlę.
  • Pominięcie deduplikacji. Meta może ponownie dostarczyć to samo zdarzenie po awarii, więc kluczem jest identyfikator komentarza lub mid wiadomości.
Z EasyCoexistence zrobisz to

easyCoexistence przekazuje komentarze, wzmianki i wiadomości DM konta Instagram na Twój endpoint HTTPS w chwili ich nadejścia, podpisane sekretem przypisanym do konta i bez zachowywania kopii po drodze. Włączasz to narzędziem set_social_webhook_destination z Claude lub ChatGPT albo przez Partner API. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, spadając wraz z dodawaniem połączeń, z bezpłatnym okresem próbnym na pierwsze 3 dni.

Najczęściej zadawane pytania

Co oznacza pole time w webhooku Instagrama?

Moment wysłania powiadomienia przez Meta, a nie chwilę utworzenia komentarza lub wiadomości. Własny znacznik czasu DM znajduje się w jego wpisie messaging.

Czy Meta ponawia nieudane dostawy webhooków Instagrama?

Tak. Meta ponawia nieudaną dostawę do aplikacji przez maksymalnie 36 godzin, więc to samo zdarzenie może sporadycznie dotrzeć dwa razy: deduplikuj je po identyfikatorze komentarza lub mid wiadomości. easyCoexistence przekazuje każde zdarzenie do Twojego endpointu jednorazowo, więc odpowiadaj szybko kodem 2xx.

Ile aktualizacji może zawierać jedna dostawa webhooka Instagrama?

Do 1 000, gdy Meta je grupuje, choć Meta nie gwarantuje grupowania. Przejdź całą tablicę entry, zamiast czytać tylko jej pierwszy element.

Czy wzmianki mają własne zdarzenie?

Nie przy Instagram Login. Meta dołącza wzmianki do powiadomienia o komentarzach, więc przychodzą tą samą ścieżką co komentarze.

Czytaj dalej

Połącz pierwszy kanał w dwie minuty.

Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.

  • 3 dni za darmo
  • Rezygnacja w każdej chwili
  • Tylko oficjalne API
  • Monitorowanie 24/7

Zweryfikowano w