Verifica dei webhook Instagram: hub.challenge e X-Hub-Signature-256
Configurare i webhook Instagram richiede un endpoint HTTPS che risponde alla GET di verifica di Meta, la quale contiene hub.mode impostato su subscribe, hub.verify_token e hub.challenge, controllando il token e restituendo il valore di hub.challenge. Meta invia poi eventi JSON firmati in X-Hub-Signature-256 con il segreto dell'app, una volta che l'app si è iscritta ai campi e ogni account è iscritto tramite il suo edge subscribed_apps.
easyCoexistence gestisce il lato Meta: la sua app supera la verifica, controlla X-Hub-Signature-256, iscrive ogni account Instagram collegato a commenti, messaggi e menzioni, e inoltra gli eventi al tuo endpoint HTTPS firmati con X-EC-Signature e con un segreto per account, monitorando ogni connessione 24 ore su 24.
Il valore hub.mode è sempre presente nella richiesta di verifica di Meta.
Periodo entro cui Meta riprova a inviare una notifica non riuscita, con frequenza decrescente, prima di scartarla.
Di consegne di messaggi non riuscite prima che Meta invii un avviso all'account dello sviluppatore.
Di consegne di messaggi non riuscite prima di un avviso Webhooks Disabled e della disiscrizione dell'app dall'account.
Modalità dell'app richiesta da Meta prima che l'app riceva notifiche per gli account dei propri utenti.
Come funziona la configurazione dei webhook Instagram?
In quattro passaggi, nell'ordine indicato dalla guida di Meta. L'endpoint deve superare la verifica prima che si possa selezionare qualsiasi campo, l'app deve essere Live per ricevere notifiche per gli account dei propri utenti, e la verifica dell'azienda è richiesta per l'accesso in produzione.
Cosa contiene la richiesta di verifica?
Una GET verso l'URL di callback, inviata ogni volta che il prodotto Webhooks viene configurato nella App Dashboard. Quando hub.verify_token coincide con il token dell'endpoint, la risposta è un 200 con il valore di hub.challenge come intero corpo; altrimenti un 403. La dashboard indica se l'endpoint ha superato la verifica.
- hub.mode: sempre subscribe.
- hub.challenge: un intero generato da Meta, che l'endpoint deve restituire.
- hub.
verify_token: la stringa inserita nel campo Verify Token della dashboard, che devono conoscere solo Meta e l'endpoint. - In PHP, i punti in questi nomi diventano trattini bassi, quindi i valori arrivano come
hub_mode,hub_challengeehub_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
1158201444Dove si impostano il callback e i campi?
Nella App Dashboard, sotto Instagram, «API setup with Instagram login, Configure webhooks»: l'URL di callback e il Verify Token vanno inseriti lì, e il salvataggio avvia la richiesta di verifica. Il prodotto Instagram parte iscritto a comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral e messaging_seen, e Manage annulla l'iscrizione a ciascuno di essi. Il pulsante Test invia una notifica di esempio per il campo selezionato.
Come si verifica X-Hub-Signature-256?
Meta firma ogni notifica di evento con un HMAC-SHA256 del payload, con chiave il segreto dell'app, e la invia in X-Hub-Signature-256 come sha256= seguito dal digest esadecimale. Il ricevente calcola lo stesso HMAC sul corpo grezzo della richiesta e lo confronta, in tempo costante, con l'intestazione. La guida di Meta sulla messaggistica precisa che la firma copre il payload con i caratteri Unicode codificati come escape, quindi calcolare l'hash di un JSON decodificato o riserializzato dà un risultato diverso.
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);Perché solo il segreto dell'app può verificarla?
Perché la firma è un HMAC con chiave quel segreto. Senza di esso nessuno può calcolare il valore atteso, e chi possiede una copia di un payload non può falsificarne uno, quindi il controllo va fatto sul server che riceve le richieste di Meta per l'app. Meta chiede che segreti dell'app, token di accesso e credenziali client restino fuori dai log e dalle richieste di assistenza. Un sistema che riceve eventi inoltrati da un'altra app non può verificare la firma di Meta e si affida invece alla firma propria di quell'app.
Perché ogni account ha bisogno della propria iscrizione?
Perché la App Dashboard stabilisce cosa l'app può ricevere, e le notifiche per un account iniziano solo quando anche quell'account è iscritto. Con Instagram Login, invia POST /<IG_ID>/subscribed_apps a graph.instagram.com con il token di accesso utente Instagram dell'account e subscribed_fields con l'elenco dei campi selezionati per l'app, separati da virgole. Una chiamata riuscita restituisce success impostato su true.
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }Cosa fa Meta quando le consegne falliscono?
Riprova, poi rinuncia. La guida di Meta chiede un 200 OK per ogni notifica e avverte che il raggruppamento, fino a 1.000 aggiornamenti, non è garantito. Un aggiornamento non riuscito viene ritentato subito, poi alcune altre volte con frequenza decrescente nell'arco di 36 ore, e scartato dopo, quindi lo stesso evento può arrivare due volte. Gli eventi di messaggistica seguono le regole di consegna dei messaggi di Meta, che agiscono più rapidamente:
- Ci si aspetta un 200 OK entro 5 secondi, e una consegna non riuscita riceve alcuni nuovi tentativi immediati, quindi deduplica sull'ID del messaggio mid.
- Dopo 15 minuti di errori, un avviso viene inviato all'account dello sviluppatore.
- Dopo un'ora di errori, segue un avviso Webhooks Disabled, e l'app viene disiscritta dai webhook dell'account finché non si iscrive di nuovo.
- I messaggi inviati durante un'interruzione possono arrivare fuori ordine, quindi ordinali per timestamp.
Cosa controllare quando non arriva nulla?
La checklist di risoluzione dei problemi di Meta, che copre la maggior parte degli endpoint silenziosi, in quest'ordine:
- L'URL di callback ha superato la verifica ed è raggiungibile in HTTPS con un certificato valido; quelli autofirmati non sono supportati.
- L'app ha selezionato il campo e ha il livello di accesso necessario, Advanced Access per comments e
live_comments. - Le notifiche sono attive per l'account tramite
subscribed_apps, con un token dello stesso flusso di login. - L'account rispetta le regole del campo: le notifiche sui commenti richiedono media di proprietà di un account pubblico.
- Il server restituisce success prima di avviare operazioni lente.
Perché easyCoexistence firma di nuovo gli eventi inoltrati?
Perché la firma di Meta non può viaggiare. L'app di easyCoexistence riceve la consegna di Meta, verifica X-Hub-Signature-256 con il proprio segreto dell'app, risponde subito a Meta e inoltra con POST ogni voce per un account collegato all'endpoint impostato per quell'account, dentro un nuovo corpo con platform, account_id, external_id ed entry. L'intestazione di Meta non viene inoltrata e non potrebbe essere verificata senza quel segreto, quindi ogni inoltro porta Content-Type: application/json e X-EC-Signature, con chiave un segreto che appartiene a quel singolo account.
Come si verifica X-EC-Signature?
L'intestazione ha la forma t=<unix>,v1=<hex>, dove v1 è l'HMAC-SHA256 esadecimale del timestamp, di un punto e del corpo grezzo, con chiave il segreto di firma dell'account. Calcolalo di nuovo sui byte esattamente come ricevuti, confrontali in tempo costante e rifiuta un timestamp più vecchio di 5 minuti.
- Il segreto inizia con whsec_ e viene mostrato una sola volta, da
set_social_webhook_destinationo da PUT /channels/:id/webhook quando si imposta l'URL. - Impostare di nuovo l'URL genera un nuovo segreto, e un URL nullo disattiva l'inoltro.
- Ogni evento viene inviato una volta, attendendo fino a 8 secondi, senza seguire i reindirizzamenti, verso un indirizzo HTTPS che risolve in un IP pubblico.
- Rimuovere la connessione annulla l'iscrizione dell'account ai webhook di Meta e cancella il suo endpoint e il suo segreto.
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())Errori comuni
- Restituire hub.challenge come JSON o tra virgolette. Meta si aspetta il valore di hub.challenge come unico corpo, con codice 200.
- Calcolare l'hash di un corpo già analizzato. Un parser JSON scarta i byte esatti firmati da Meta, quindi conserva il corpo grezzo per l'HMAC e analizzalo dopo.
- Iscrivere l'app e dimenticare l'account. Finché POST /<IG_ID>/subscribed_apps non riesce per un account, per quell'account non arriva alcuna notifica.
- Lasciare che un endpoint fallisca per un'ora. Meta disabilita i webhook di messaggistica e disiscrive l'app dall'account, che va poi iscritto di nuovo.
Attivalo con set_social_webhook_destination o con la Partner API. Da US$ 9 a US$ 0,75 per connessione al mese, che scende man mano che aggiungi connessioni, con i primi 3 giorni di prova gratuita.
Domande frequenti
Cos'è hub.challenge nei webhook Instagram?
Un intero che Meta invia nella sua GET di verifica. Dopo aver controllato hub.verify_token, l'endpoint lo restituisce come corpo della risposta, dimostrando di controllare l'URL.
Perché hub.mode e hub.challenge mancano in PHP?
PHP trasforma i punti nei nomi dei parametri in trattini bassi, quindi i valori di verifica di Meta arrivano come hub_mode, hub_challenge e hub_verify_token.
Come riattivo i webhook Instagram dopo che Meta li ha disabilitati?
Correggi l'endpoint, poi iscrivi di nuovo l'account con POST /<IG_ID>/subscribed_apps e gli stessi campi.
Un certificato autofirmato funziona per un endpoint webhook Instagram?
No, Meta non supporta i certificati autofirmati: l'URL di callback deve essere raggiungibile in HTTPS con un certificato valido, primo punto della checklist di risoluzione dei problemi di Meta.
Continua a leggere
Collega il tuo primo canale in due minuti.
Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.
- 3 giorni gratis
- Disdici quando vuoi
- Solo API ufficiali
- Monitorato 24/7
Verificato il