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ę.
Wartość hub.mode zawsze występuje w weryfikacyjnym żądaniu Meta.
Okres, przez który Meta ponawia nieudane powiadomienie z malejącą częstotliwością, zanim je odrzuci.
Nieudanych dostarczeń wiadomości, zanim Meta wyśle alert do konta dewelopera.
Nieudanych dostarczeń wiadomości, po których pojawia się alert Webhooks Disabled i aplikacja zostaje wypisana z konta.
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.
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_challengeihub_verify_token.
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
1158201444Gdzie 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.
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.
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_destinationlub 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.
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.
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