InloggenGratis proefperiode starten
easyCoexistence Officiële API's

Facebook-webhookverificatie: hub.challenge en X-Hub-Signature-256

Facebook verifieert een webhook-endpoint met een GET met hub.mode ingesteld op subscribe, hub.verify_token en hub.challenge; het endpoint controleert het token tegen dat in het App Dashboard en geeft de waarde van hub.challenge terug als body. Daarna komt elk event binnen als een POST, ondertekend in X-Hub-Signature-256: sha256= gevolgd door de HMAC-SHA256 van de payload, met het App Secret als sleutel.

easyCoexistence regelt de kant van Meta voor elke Pagina die je koppelt: de app beantwoordt hub.challenge, controleert X-Hub-Signature-256 en abonneert de Pagina op feed, berichten en vermeldingen, en stuurt de events daarna door naar je HTTPS-endpoint, ondertekend met X-EC-Signature en een geheim voor die Pagina.

subscribe

De waarde die hub.mode altijd bevat in het verificatieverzoek van Meta; hub.challenge is een geheel getal dat je terugstuurt.

sha256=

Voorvoegsel van X-Hub-Signature-256, gevolgd door de SHA256-handtekening die Meta genereert uit de payload en het App Secret.

5 seconds

Hoe snel een Messenger-webhook-endpoint elke melding met 200 OK moet beantwoorden.

1 hour

Van mislukte leveringen voordat een Webhooks Disabled-waarschuwing volgt en de app zich van de Pagina afmeldt.

36 hours

Hoe lang Meta een mislukte Pagina-melding opnieuw probeert, met afnemende frequentie, voordat die wordt weggegooid.

Wat bevat het verificatieverzoek van Meta?

Een GET naar de callback-URL, verstuurd zodra het product Webhooks in het App Dashboard is ingesteld of wanneer een abonnement wordt aangemaakt via /{app-id}/subscriptions. Er komen drie queryparameters mee:

  • hub.mode: altijd subscribe.
  • hub.challenge: een geheel getal dat het endpoint moet teruggeven.
  • hub.verify_token: de tekst die je invult in het veld Verify Token van het dashboard.
  • PHP zet de punten om in underscores, dus leest het ze als hub_mode, hub_challenge en hub_verify_token.

Hoe moet het endpoint daarop antwoorden?

Met een 200 waarvan de volledige body de waarde van hub.challenge is, maar alleen als hub.mode subscribe is en hub.verify_token overeenkomt. Alles anders krijgt een 403, zoals in Meta's voorbeeld-app. Het dashboard meldt of het endpoint is geslaagd, en /{app-id}/subscriptions antwoordt met succes of een fout. Het endpoint vereist HTTPS met een geldig TLS- of SSL-certificaat, want zelfondertekende certificaten worden niet ondersteund.

Hoe wordt X-Hub-Signature-256 berekend?

Als HMAC-SHA256 van de payload van het verzoek, gesleuteld met het App Secret van de app, in kleine hexadecimale letters na sha256=. In Meta's Messenger-gids staat dat de handtekening de payload dekt met Unicode geëscapet, dus een tekst als äöå telt als \u00e4\u00f6\u00e5: hash de ruwe body precies zoals ontvangen, nooit een gedecodeerde of opnieuw geserialiseerde kopie. Meta zegt dat valideren optioneel is, maar sterk aanbevolen wordt.

Hoe controleer je dit in code?

Bewaar de ruwe bytes, bereken de HMAC, vergelijk in constante tijd en parse daarna pas. Flask's get_data geeft de body onaangeroerd terug, en daarover is de handtekening berekend; eerst parsen en daarna opnieuw serialiseren zou de bytes veranderen. Een klein endpoint dat de verificatie afhandelt en elke POST controleert:

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

Wat verwacht Meta na de verificatie?

Een 200 OK voor elke melding, binnen 5 seconden voor Messenger-events. Meta bundelt tot 1.000 updates per levering zonder dat te garanderen, en gaat zo met fouten om:

  • Pagina-meldingen: direct opnieuw geprobeerd, daarna enkele keren met afnemende frequentie over 36 uur, en dan weggegooid.
  • Messenger-meldingen: enkele keren direct opnieuw geprobeerd; na 15 minuten mislukken komt er een waarschuwing bij het ontwikkelaarsaccount.
  • Na een uur mislukken volgt een Webhooks Disabled-waarschuwing en wordt de app van de Pagina afgemeld tot ze zich opnieuw abonneert.
  • Nieuwe pogingen kunnen een event twee keer en door elkaar leveren, dus dedupliceer en sorteer berichten op hun tijdstempel.
  • Eerdere meldingen kunnen later niet worden opgevraagd, dus sla op wat je nodig hebt zodra het binnenkomt.

Hoe voldoet easyCoexistence aan de controles van Meta?

De Meta-app heeft één callback-URL voor de Pagina's die het koppelt, en dat endpoint voert beide controles zelf uit. Het beantwoordt de GET alleen als hub.mode subscribe is en het verify token overeenkomt, vergeleken in constante tijd, en geeft anders een 403. Het leest elke POST als ruwe tekst, berekent X-Hub-Signature-256 opnieuw met zijn App Secret, weigert een niet-passende handtekening met een 401 en antwoordt Meta meteen, waarna het het event verwerkt.

Hoe ondertekent easyCoexistence wat het doorstuurt?

Met een eigen handtekening, want de header van Meta kan alleen worden gecontroleerd met het App Secret van easyCoexistence en wordt niet doorgegeven. Elke entry voor een verbonden Pagina waarvoor een endpoint is ingesteld, wordt daarheen als JSON gepost, {platform, account_id, external_id, entry}, met een X-EC-Signature-header in de vorm t=<unix>,v1=<hex>. Daarin is v1 de HMAC-SHA256 van het tijdstempel, een punt en de ruwe body, gesleuteld met het ondertekeningsgeheim van die Pagina:

  • Het geheim begint met whsec_ en wordt één keer getoond, door set_social_webhook_destination of PUT /channels/:id/webhook op de Partner API.
  • Het URL opnieuw instellen geeft een nieuw geheim, en een null-URL zet het doorsturen uit.
  • Elke doorgestuurde melding wordt één keer verstuurd, met een wachttijd tot 8 seconden, zonder omleidingen te volgen, naar een HTTPS-adres dat naar een publiek IP-adres verwijst.
  • Er wordt geen kopie van het event bewaard, dus er is niets om opnieuw te proberen.

Hoe verifieer je X-EC-Signature?

Splits de header in t en v1, wijs een tijdstempel af dat ouder is dan 5 minuten, bereken de HMAC opnieuw over t, een punt en de ruwe body met het ondertekeningsgeheim van de Pagina, en vergelijk in constante tijd. In Node.js, met de body bewaard als ruwe bytes:

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

Veelgemaakte fouten

  • hub.challenge in JSON of aanhalingstekens zetten. De body van de 200 moet de challengewaarde zelf zijn.
  • De HMAC berekenen na een JSON-parser. Parsen en opnieuw serialiseren verandert de bytes, en Meta ondertekent de payload met Unicode geëscapet, dus hash de ruwe body.
  • Het werk doen voordat je antwoordt. Messenger verwacht een 200 binnen 5 seconden, en een uur mislukken haalt de app van de Pagina af.
  • Meta's handtekening controleren op doorgestuurde events. Meta ondertekent met het App Secret van easyCoexistence; een doorgestuurd event draagt X-EC-Signature, gecontroleerd met het ondertekeningsgeheim van de Pagina.
Dit doen met EasyCoexistence

US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je meer verbindingen toevoegt, met de eerste 3 dagen gratis.

Veelgestelde vragen

Waar komt het verify token vandaan?

Dat kies je zelf. Het is de tekst die je invult in het veld Verify Token bij het instellen van webhooks in het App Dashboard, of het verify_token dat je naar /{app-id}/subscriptions stuurt.

Kan ik de verificatie testen met curl?

Ja. Meta's Messenger-gids stuurt een GET met hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED en hub.mode=subscribe, en een werkend endpoint antwoordt met CHALLENGE_ACCEPTED.

Wat gebeurt er als mijn endpoint een uur lang faalt?

Meta stuurt een Webhooks Disabled-waarschuwing en meldt de app af van de Pagina. Repareer het endpoint en abonneer de Pagina daarna opnieuw via subscribed_apps.

Heb ik een eigen Meta-app nodig om webhooks van een Pagina te ontvangen?

Niet met easyCoexistence. Meta levert aan de eigen app, die de events van elke Pagina doorstuurt naar het endpoint dat je instelt, ondertekend met X-EC-Signature.

Lees verder

Koppel je eerste kanaal in twee minuten.

Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.

  • 3 dagen gratis
  • Op elk moment opzegbaar
  • Alleen officiële API's
  • 24/7 bewaakt

Geverifieerd op