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

Weryfikacja webhooków Instagram: hub.challenge i X-Hub-Signature-256

Konfiguracja webhooków Instagram wymaga endpointu HTTPS, który odpowiada na weryfikacyjne żądanie GET Meta. Zawiera ono hub.mode z wartością subscribe, hub.verify_token i hub.challenge. Endpoint sprawdza token i zwraca challenge. Następnie Meta wysyła zdarzenia JSON podpisane w nagłówku X-Hub-Signature-256 sekretem aplikacji, gdy aplikacja subskrybuje pola, a każde konto zostaje zasubskrybowane przez swoją krawędź subscribed_apps.

easyCoexistence obsługuje stronę Meta: jego aplikacja przechodzi weryfikację, sprawdza X-Hub-Signature-256, subskrybuje każde podłączone konto Instagram do komentarzy, wiadomości i wzmianek oraz przekazuje zdarzenia na Twój endpoint HTTPS, podpisane X-EC-Signature i sekretem dla każdego konta, a każde połączenie monitoruje całą dobę.

subscribe

Wartość hub.mode zawsze występuje w weryfikacyjnym żądaniu Meta.

36 hours

Okres, przez który Meta ponawia nieudane powiadomienie z malejącą częstotliwością, zanim je odrzuci.

15 minutes

Nieudanych dostarczeń wiadomości, zanim Meta wyśle alert do konta dewelopera.

1 hour

Nieudanych dostarczeń wiadomości, po których pojawia się alert Webhooks Disabled i aplikacja zostaje wypisana z konta.

Live

Tryb aplikacji, którego Meta wymaga, zanim aplikacja otrzyma powiadomienia o kontach swoich użytkowników.

Jak działa konfiguracja webhooków Instagram?

W czterech krokach, w kolejności podanej w przewodniku Meta. Endpoint musi przejść weryfikację, zanim można wybrać jakiekolwiek pole. Aplikacja musi być w trybie Live, by otrzymywać powiadomienia o kontach użytkowników, a do dostępu produkcyjnego wymagana jest weryfikacja firmy.

1EndpointAn HTTPS URL with a valid certificate answers the verification GET
2App fieldsCallback URL, verify token and fields set in the App Dashboard
3Each accountPOST /<IG_ID>/subscribed_apps turns its notifications on
4TestA dashboard test, then a real event, reach the endpoint

Co zawiera żądanie weryfikacyjne?

Żądanie GET na adres callback, wysyłane zawsze, gdy produkt Webhooks jest skonfigurowany w App Dashboard. Gdy hub.verify_token zgadza się z tokenem własnym endpointu, odpowiedzią jest 200 z wartością hub.challenge jako całą treścią; w przeciwnym razie 403. Panel pokazuje, czy endpoint przeszedł weryfikację.

  • hub.mode: zawsze subscribe.
  • hub.challenge: liczba całkowita wygenerowana przez Meta, którą endpoint musi odesłać.
  • hub.verify_token: ciąg wpisany w polu Verify Token w panelu, znany tylko Meta i endpointowi.
  • W PHP kropki w tych nazwach zamieniają się na podkreślenia, więc wartości docierają jako hub_mode, hub_challenge i hub_verify_token.
The verification request and its answer
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

Gdzie ustawia się callback i pola?

W App Dashboard, w sekcji Instagram, API setup with Instagram login, `Configure webhooks`: tam wpisuje się adres callback i verify token, a zapisanie ich uruchamia żądanie weryfikacyjne. Produkt Instagram domyślnie subskrybuje pola comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral i messaging_seen, a przycisk Manage pozwala z dowolnego z nich zrezygnować. Przycisk Test wysyła przykładowe powiadomienie dla wybranego pola.

Jak sprawdza się X-Hub-Signature-256?

Meta podpisuje każde powiadomienie o zdarzeniu HMAC-SHA256 z treści, kluczowanym sekretem aplikacji, i wysyła je w nagłówku X-Hub-Signature-256 jako sha256= oraz szesnastkowy wynik. Odbiorca oblicza ten sam HMAC z surowej treści żądania i porównuje go z nagłówkiem w stałym czasie. Przewodnik Meta dla wiadomości zwraca uwagę, że podpis obejmuje ładunek z escapowanym Unicode, więc hashowanie zdekodowanego lub ponownie zserializowanego JSON daje inny wynik.

Node.js: answering verification and checking X-Hub-Signature-256
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);

Dlaczego sprawdzić może tylko sekret aplikacji?

Bo podpis jest HMAC kluczowanym tym sekretem. Bez niego nikt nie obliczy oczekiwanej wartości, a nikt posiadający kopię ładunku nie sfałszuje go, więc sprawdzenie należy do serwera, który odbiera żądania Meta dla aplikacji. Meta prosi, by sekrety aplikacji, tokeny dostępu i dane uwierzytelniające klienta nie trafiały do logów ani zgłoszeń do supportu. System, który odbiera zdarzenia przekazane przez inną aplikację, nie może sprawdzić podpisu Meta i opiera się zamiast tego na podpisie tamtej aplikacji.

Dlaczego każde konto potrzebuje własnej subskrypcji?

Bo App Dashboard określa, co aplikacja może odbierać, ale powiadomienia o koncie zaczynają płynąć dopiero wtedy, gdy także to konto zostanie zasubskrybowane. Przy Instagram Login wyślij POST /<IG_ID>/subscribed_apps na graph.instagram.com, z tokenem dostępu użytkownika Instagram tego konta i subscribed_fields zawierającym pola wybrane dla aplikacji, oddzielone przecinkami. Udane wywołanie zwraca success ustawione na true.

Subscribing one account to comments and messages
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
  ?subscribed_fields=comments,messages
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

{ "success": true }

Co robi Meta, gdy dostarczenia się nie udają?

Ponawia, a potem rezygnuje. Przewodnik Meta wymaga odpowiedzi 200 OK na każde powiadomienie i ostrzega, że grupowanie, do 1 000 aktualizacji, nie jest gwarantowane. Nieudana aktualizacja jest ponawiana od razu, potem kilka razy z malejącą częstotliwością przez 36 godzin, a po tym odrzucana, więc to samo zdarzenie może przyjść dwukrotnie. Zdarzenia wiadomości podlegają regułom dostarczania wiadomości Meta, które działają szybciej:

  • Oczekiwana jest odpowiedź 200 OK w ciągu 5 sekund, a nieudane dostarczenie dostaje kilka natychmiastowych ponowień, więc deduplikuj po message mid.
  • Po 15 minutach niepowodzeń alert trafia na konto dewelopera.
  • Po godzinie niepowodzeń pojawia się alert Webhooks Disabled, a aplikacja zostaje wypisana z webhooków konta, dopóki nie zasubskrybuje ich ponownie.
  • Wiadomości wysłane podczas awarii mogą dotrzeć w złej kolejności, więc sortuj je po timestamp.

Co sprawdzić, gdy nic nie przychodzi?

Listę kontrolną rozwiązywania problemów Meta, która obejmuje większość cichych endpointów, w tej kolejności:

  • Adres callback przeszedł weryfikację i jest osiągalny przez HTTPS z ważnym certyfikatem; certyfikaty self-signed nie są obsługiwane.
  • Aplikacja wybrała pole i ma potrzebny poziom dostępu, Advanced Access dla comments i live_comments.
  • Powiadomienia są włączone dla konta przez subscribed_apps, z tokenem z tej samej konfiguracji logowania.
  • Konto spełnia zasady pola: powiadomienia o komentarzach wymagają mediów należących do konta publicznego.
  • Serwer zwraca sukces, zanim zacznie wolną pracę.

Dlaczego easyCoexistence podpisuje przekazywane zdarzenia ponownie?

Bo podpisu Meta nie da się przekazać dalej. Aplikacja easyCoexistence odbiera dostarczenie od Meta, sprawdza X-Hub-Signature-256 własnym sekretem aplikacji, od razu odpowiada Meta i wysyła każdy wpis dla podłączonego konta na endpoint ustawiony dla tego konta, w nowej treści zawierającej platform, account_id, external_id i entry. Nagłówek Meta nie jest przekazywany i nie dałoby się go sprawdzić bez tego sekretu, dlatego każde przekazanie niesie Content-Type: application/json oraz X-EC-Signature, kluczowany sekretem należącym do tego jednego konta.

Jak zweryfikować X-EC-Signature?

Nagłówek ma postać t=<unix>,v1=<hex>, gdzie v1 to szesnastkowy HMAC-SHA256 znacznika czasu, kropki i surowej treści, kluczowany sekretem podpisu konta. Oblicz go ponownie na bajtach dokładnie w takiej postaci, w jakiej przyszły, porównaj w stałym czasie i odrzuć znacznik czasu starszy niż 5 minut.

  • Sekret zaczyna się od whsec_ i jest pokazany jednorazowo przez set_social_webhook_destination lub PUT /channels/:id/webhook, gdy ustawiany jest adres.
  • Ponowne ustawienie adresu wystawia nowy sekret, a pusty adres (null) wyłącza przekazywanie.
  • Każde zdarzenie wysyłane jest raz, z limitem oczekiwania 8 sekund, bez podążania za przekierowaniami, na adres HTTPS rozwiązujący się do publicznego IP.
  • Usunięcie połączenia wypisuje konto z webhooków Meta i czyści jego endpoint oraz sekret.
Python: checking X-EC-Signature
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())

Typowe błędy

  • Zwracanie challenge jako JSON lub w cudzysłowie. Meta oczekuje samej wartości hub.challenge jako treści, ze statusem 200.
  • Hashowanie sparsowanej treści. Parser JSON odrzuca dokładne bajty, które Meta podpisała, więc zachowaj surową treść do HMAC i sparsuj ją później.
  • Subskrybowanie aplikacji, a zapomnienie o koncie. Dopóki POST /<IG_ID>/subscribed_apps nie powiedzie się dla konta, nie przychodzą dla niego żadne powiadomienia.
  • Pozwolenie, by endpoint działał błędnie przez godzinę. Meta wyłącza webhooki wiadomości i wypisuje aplikację z konta, które trzeba wtedy zasubskrybować ponownie.
Z EasyCoexistence zrobisz to

Włącz to przez set_social_webhook_destination lub Partner API. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, spadając wraz z dodawaniem połączeń, z pierwszymi 3 dniami w bezpłatnym okresie próbnym.

Najczęściej zadawane pytania

Czym jest hub.challenge w webhookach Instagram?

Liczbą całkowitą, którą Meta wysyła w swoim żądaniu GET weryfikacyjnym. Po sprawdzeniu hub.verify_token endpoint zwraca ją jako treść odpowiedzi, co dowodzi, że kontroluje adres URL.

Dlaczego w PHP brakuje hub.mode i hub.challenge?

PHP zamienia kropki w nazwach parametrów na podkreślenia, więc wartości weryfikacyjne Meta docierają jako hub_mode, hub_challenge i hub_verify_token.

Jak ponownie włączyć webhooki Instagram po wyłączeniu ich przez Meta?

Napraw endpoint, a następnie zasubskrybuj konto ponownie poleceniem POST /<IG_ID>/subscribed_apps z tymi samymi polami.

Czy certyfikat self-signed działa dla endpointu webhooka Instagram?

Nie, Meta nie obsługuje certyfikatów self-signed: adres callback musi być osiągalny przez HTTPS z ważnym certyfikatem, to pierwszy punkt listy kontrolnej Meta.

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