Log inStart Free Trial
easyCoexistence Official APIs

Facebook webhook verification: hub.challenge and X-Hub-Signature-256

Facebook verifies a webhook endpoint with a GET carrying hub.mode set to subscribe, hub.verify_token and hub.challenge; the endpoint checks the token against the one in the App Dashboard and returns the challenge as the body. Each event then arrives as a POST signed in X-Hub-Signature-256: sha256= followed by the HMAC-SHA256 of the payload, keyed with the app secret.

easyCoexistence handles Meta's side for each Page you connect: its app answers hub.challenge, checks X-Hub-Signature-256 and subscribes the Page to feed, messages and mention, then forwards the events to your HTTPS endpoint signed with X-EC-Signature and a secret for that Page.

subscribe

The value hub.mode always carries in Meta's verification request; hub.challenge is an integer to send back.

sha256=

Prefix of X-Hub-Signature-256, followed by the SHA256 signature Meta generates from the payload and the App Secret.

5 seconds

How quickly a Messenger webhook endpoint should answer each notification with 200 OK.

1 hour

Of failing deliveries before a Webhooks Disabled alert and the app's unsubscription from the Page.

36 hours

How long Meta retries a failed Page notification, with decreasing frequency, before dropping it.

What does Meta's verification request contain?

A GET to the callback URL, sent whenever the Webhooks product is configured in the App Dashboard or a subscription is created through /{app-id}/subscriptions. Three query parameters come with it:

  • hub.mode: always subscribe.
  • hub.challenge: an integer the endpoint must send back.
  • hub.verify_token: the string entered in the dashboard's Verify Token field.
  • PHP turns the dots into underscores, so it reads them as hub_mode, hub_challenge and hub_verify_token.

How should the endpoint answer it?

With a 200 whose whole body is the hub.challenge value, but only when hub.mode is subscribe and hub.verify_token matches; anything else gets a 403, as in Meta's sample app. The dashboard reports whether the endpoint passed, and /{app-id}/subscriptions answers with success or an error. The endpoint needs HTTPS with a valid TLS or SSL certificate, since self-signed certificates are not supported.

How is X-Hub-Signature-256 computed?

As an HMAC-SHA256 of the request payload keyed with the app's App Secret, written in lowercase hex after sha256=. Meta's Messenger guide adds that the signature covers the payload with Unicode escaped, so a string such as äöå counts as \u00e4\u00f6\u00e5: hash the raw body exactly as received, never a decoded or re-serialized copy. Meta says validating is optional but strongly recommends it.

How do you check it in code?

Keep the raw bytes, compute the HMAC, compare in constant time, then parse. Flask's get_data returns the body untouched, which is what the signature was computed over; parsing it first and serializing it again would change the bytes. A small endpoint that answers verification and checks each 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

What does Meta expect after verification?

A 200 OK for each notification, within 5 seconds for Messenger events. Meta batches up to 1,000 updates per delivery without guaranteeing it, and handles failures this way:

  • Page notifications: retried at once, then a few more times with decreasing frequency over 36 hours, then dropped.
  • Messenger notifications: retried a few times at once; after 15 minutes of failures, an alert reaches the developer account.
  • After an hour of failures, a Webhooks Disabled alert follows and the app is unsubscribed from the Page until it subscribes again.
  • Retries can deliver an event twice and out of order, so deduplicate, and sort messages by their timestamp.
  • Past notifications cannot be queried later, so store what you need as it arrives.

How does easyCoexistence pass Meta's checks?

Its Meta app has one callback URL for the Pages it connects, and that endpoint does both checks itself. It answers the GET only when hub.mode is subscribe and the verify token matches, compared in constant time, and returns 403 otherwise; it reads each POST as raw text, recomputes X-Hub-Signature-256 with its app secret, refuses a mismatch with 401, and answers Meta at once, handling the event after the response.

How does easyCoexistence sign what it forwards?

With a signature of its own, since Meta's header can only be checked with easyCoexistence's app secret and is not passed on. Each entry for a connected Page with an endpoint set is POSTed there as JSON, {platform, account_id, external_id, entry}, with an X-EC-Signature header in the form t=<unix>,v1=<hex>, where v1 is the HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with that Page's signing secret:

  • The secret starts with whsec_ and is shown once, by set_social_webhook_destination or PUT /channels/:id/webhook on the Partner API.
  • Setting the URL again issues a new secret, and a null URL turns forwarding off.
  • Each forward is sent once, waiting up to 8 seconds, without following redirects, to an HTTPS address that resolves to a public IP.
  • No copy of the event is kept, so there is nothing to retry from.

How do you verify X-EC-Signature?

Split the header into t and v1, reject a timestamp more than 5 minutes old, recompute the HMAC over t, a dot and the raw body with the Page's signing secret, and compare in constant time. In Node.js, with the body kept as raw 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
});

Common mistakes

  • Wrapping hub.challenge in JSON or quotes. The body of the 200 has to be the challenge value itself.
  • Computing the HMAC after a JSON parser. Parsing and re-serializing changes the bytes, and Meta signs the payload with Unicode escaped, so hash the raw body.
  • Doing the work before answering. Messenger expects a 200 within 5 seconds, and an hour of failures unsubscribes the app from the Page.
  • Checking Meta's signature on forwarded events. Meta signs with easyCoexistence's app secret; a forwarded event carries X-EC-Signature, checked with the Page's signing secret.
Doing this with EasyCoexistence

US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

Where does the verify token come from?

You choose it. It is the string entered in the Verify Token field when configuring webhooks in the App Dashboard, or the verify_token sent to /{app-id}/subscriptions.

Can I test verification with curl?

Yes. Meta's Messenger guide sends a GET with hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED and hub.mode=subscribe, and a working endpoint answers CHALLENGE_ACCEPTED.

What happens if my endpoint fails for an hour?

Meta sends a Webhooks Disabled alert and unsubscribes the app from the Page. After fixing the endpoint, subscribe the Page again through subscribed_apps.

Do I need my own Meta app to receive a Page's webhooks?

Not with easyCoexistence. Meta delivers to its app, which forwards each Page's events to the endpoint you set, signed with X-EC-Signature.

Keep reading

Connect your first channel in two minutes.

No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.

  • 3 days free
  • Cancel any time
  • Official APIs only
  • Monitored 24/7

Verified on