AccediInizia la prova gratuita
easyCoexistence API ufficiali

Verifica webhook Facebook: hub.challenge e X-Hub-Signature-256

Facebook verifica un endpoint webhook con una GET che contiene hub.mode impostato su subscribe, hub.verify_token e hub.challenge; l'endpoint confronta il token con quello nell'App Dashboard e restituisce la challenge nel corpo. Ogni evento arriva poi come POST firmato in X-Hub-Signature-256: sha256= seguito dall'HMAC-SHA256 del payload, con chiave l'App Secret.

easyCoexistence gestisce la parte di Meta per ogni Pagina che colleghi: la sua app risponde a hub.challenge, verifica X-Hub-Signature-256 e iscrive la Pagina a feed, messaggi e menzioni, poi inoltra gli eventi al tuo endpoint HTTPS firmati con X-EC-Signature e con un segreto dedicato a quella Pagina.

subscribe

Il valore che hub.mode riporta sempre nella richiesta di verifica di Meta; hub.challenge è un intero da rinviare.

sha256=

Prefisso di X-Hub-Signature-256, seguito dalla firma SHA256 che Meta genera dal payload e dall'App Secret.

5 seconds

Con quale rapidità un endpoint webhook di Messenger dovrebbe rispondere a ogni notifica con 200 OK.

1 hour

Di consegne fallite prima di un avviso Webhooks Disabled e della disiscrizione dell'app dalla Pagina.

36 hours

Per quanto tempo Meta riprova una notifica di Pagina fallita, con frequenza decrescente, prima di scartarla.

Cosa contiene la richiesta di verifica di Meta?

Una GET verso l'URL di callback, inviata ogni volta che il prodotto Webhooks è configurato nell'App Dashboard o che una sottoscrizione viene creata tramite /{app-id}/subscriptions. Con essa arrivano tre parametri di query:

  • hub.mode: sempre subscribe.
  • hub.challenge: un intero che l'endpoint deve rinviare.
  • hub.verify_token: la stringa inserita nel campo Verify Token dell'App Dashboard.
  • PHP trasforma i punti in underscore, quindi li legge come hub_mode, hub_challenge e hub_verify_token.

Come deve rispondere l'endpoint?

Con un 200 il cui intero corpo è il valore di hub.challenge, ma solo quando hub.mode è subscribe e hub.verify_token coincide; in ogni altro caso restituisce un 403, come nell'app di esempio di Meta. La dashboard segnala se l'endpoint ha superato il controllo, e /{app-id}/subscriptions risponde con success o con un errore. L'endpoint richiede HTTPS con un certificato TLS o SSL valido, perché i certificati autofirmati non sono supportati.

Come si calcola X-Hub-Signature-256?

Come HMAC-SHA256 del payload della richiesta, con chiave l'App Secret dell'app, scritto in esadecimale minuscolo dopo sha256=. La guida di Meta per Messenger aggiunge che la firma copre il payload con l'Unicode escaped, quindi una stringa come äöå conta come \u00e4\u00f6\u00e5: calcola l'hash del corpo grezzo esattamente come ricevuto, mai una copia decodificata o serializzata di nuovo. Meta afferma che la validazione è facoltativa, ma la raccomanda con forza.

Come si verifica nel codice?

Conserva i byte grezzi, calcola l'HMAC, confrontalo in tempo costante, poi analizzalo. Il get_data di Flask restituisce il corpo intatto, cioè quello su cui è stata calcolata la firma; analizzarlo prima e serializzarlo di nuovo ne cambierebbe i byte. Un piccolo endpoint che risponde alla verifica e controlla ogni POST:

Python: hub.challenge and X-Hub-Signature-256
import hashlib, hmac, os
from flask import Flask, abort, request

app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()

@app.get("/webhooks/facebook")
def verify():
    token = request.args.get("hub.verify_token", "")
    if request.args.get("hub.mode") == "subscribe" and hmac.compare_digest(token.encode(), VERIFY_TOKEN.encode()):
        return request.args.get("hub.challenge", ""), 200
    abort(403)

@app.post("/webhooks/facebook")
def receive():
    raw = request.get_data()  # the bytes Meta signed
    expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected.encode(), request.headers.get("X-Hub-Signature-256", "").encode()):
        abort(401)
    # answer at once; hand request.get_json() to a queue for the work
    return "EVENT_RECEIVED", 200

Cosa si aspetta Meta dopo la verifica?

Un 200 OK per ogni notifica, entro 5 secondi per gli eventi Messenger. Meta raggruppa fino a 1.000 aggiornamenti per consegna senza garantirlo, e gestisce i fallimenti così:

  • Notifiche di Pagina: ritentate subito, poi alcune volte in più con frequenza decrescente nell'arco di 36 ore, poi scartate.
  • Notifiche Messenger: ritentate alcune volte subito; dopo 15 minuti di fallimenti, un avviso arriva all'account dello sviluppatore.
  • Dopo un'ora di fallimenti arriva un avviso Webhooks Disabled e l'app viene disiscritta dalla Pagina finché non si iscrive di nuovo.
  • I tentativi possono consegnare un evento due volte e fuori ordine, quindi deduplica e ordina i messaggi per timestamp.
  • Le notifiche passate non si possono interrogare in seguito, quindi salva ciò che ti serve appena arriva.

Come easyCoexistence supera i controlli di Meta?

La sua app Meta ha un unico URL di callback per le Pagine che collega, e quell'endpoint esegue lui stesso entrambi i controlli. Risponde alla GET solo quando hub.mode è subscribe e il verify token coincide, confrontato in tempo costante, e restituisce 403 altrimenti; legge ogni POST come testo grezzo, ricalcola X-Hub-Signature-256 con la propria App Secret, rifiuta una discrepanza con 401 e risponde subito a Meta, gestendo l'evento dopo la risposta.

Come easyCoexistence firma ciò che inoltra?

Con una firma propria, poiché l'header di Meta si può verificare solo con l'App Secret di easyCoexistence e non viene trasmesso. Ogni voce per una Pagina collegata con un endpoint impostato viene inviata via POST in JSON, {platform, account_id, external_id, entry}, con un header X-EC-Signature nella forma t=<unix>,v1=<hex>, dove v1 è l'HMAC-SHA256 del timestamp, di un punto e del corpo grezzo, con chiave il segreto di firma di quella Pagina:

  • Il segreto inizia con whsec_ e viene mostrato una sola volta, da set_social_webhook_destination o da PUT /channels/:id/webhook nella Partner API.
  • Impostare di nuovo l'URL genera un nuovo segreto, e un URL null disattiva l'inoltro.
  • Ogni inoltro viene inviato una sola volta, attendendo fino a 8 secondi, senza seguire i reindirizzamenti, verso un indirizzo HTTPS che risolve in un IP pubblico.
  • Nessuna copia dell'evento viene conservata, quindi non c'è nulla da cui riprovare.

Come si verifica X-EC-Signature?

Separa l'header in t e v1, rifiuta un timestamp più vecchio di 5 minuti, ricalcola l'HMAC su t, un punto e il corpo grezzo con il segreto di firma della Pagina, e confrontalo in tempo costante. In Node.js, con il corpo conservato come byte grezzi:

Node.js: checking X-EC-Signature on a forwarded event
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.EC_SIGNING_SECRET; // whsec_..., shown once

app.post("/events/facebook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    String(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("="))
  );
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(Buffer.concat([Buffer.from(`${sig.t}.`), req.body]))
    .digest("hex");
  const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
  if (!ok) return res.sendStatus(401);
  res.sendStatus(200); // answer first: forwards are not retried
  const { platform, account_id, external_id, entry } = JSON.parse(req.body.toString("utf8"));
  // queue entry for the work
});

Errori comuni

  • Racchiudere hub.challenge in JSON o tra virgolette. Il corpo del 200 deve essere il valore della challenge stesso.
  • Calcolare l'HMAC dopo un parser JSON. Analizzare e serializzare di nuovo cambia i byte, e Meta firma il payload con l'Unicode escaped, quindi calcola l'hash del corpo grezzo.
  • Svolgere il lavoro prima di rispondere. Messenger si aspetta un 200 entro 5 secondi, e un'ora di fallimenti disiscrive l'app dalla Pagina.
  • Controllare la firma di Meta sugli eventi inoltrati. Meta firma con l'App Secret di easyCoexistence; un evento inoltrato porta X-EC-Signature, che si verifica con il segreto di firma della Pagina.
Farlo con EasyCoexistence

US$ 9 fino a US$ 0,75 per connessione al mese, con prezzo decrescente man mano che aggiungi connessioni, con i primi 3 giorni di prova gratuita.

Domande frequenti

Da dove viene il verify token?

Lo scegli tu. È la stringa inserita nel campo Verify Token quando configuri i webhook nell'App Dashboard, oppure il verify_token inviato a /{app-id}/subscriptions.

Posso testare la verifica con curl?

Sì. La guida di Meta per Messenger invia una GET con hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED e hub.mode=subscribe, e un endpoint funzionante risponde CHALLENGE_ACCEPTED.

Cosa succede se il mio endpoint fallisce per un'ora?

Meta invia un avviso Webhooks Disabled e disiscrive l'app dalla Pagina. Dopo aver corretto l'endpoint, iscrivi di nuovo la Pagina tramite subscribed_apps.

Ho bisogno di una mia app Meta per ricevere i webhook di una Pagina?

No, con easyCoexistence. Meta consegna alla sua app, che inoltra gli eventi di ogni Pagina all'endpoint che imposti, firmati con X-EC-Signature.

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