Instagram webhook verification: hub.challenge and X-Hub-Signature-256
Setting up Instagram webhooks takes an HTTPS endpoint that answers Meta's verification GET, which carries hub.mode set to subscribe, hub.verify_token and hub.challenge, by checking the token and returning the challenge. Meta then POSTs JSON events signed in X-Hub-Signature-256 with the app's secret, once the app subscribes to fields and each account is subscribed through its subscribed_apps edge.
easyCoexistence handles the Meta side: its app passes verification, checks X-Hub-Signature-256, subscribes each connected Instagram account to comments, messages and mentions, and forwards the events to your HTTPS endpoint signed with X-EC-Signature and a secret per account, while watching each connection around the clock.
The value hub.mode always carries on Meta's verification request.
Period over which Meta retries a failed notification, with decreasing frequency, before dropping it.
Of failed messaging deliveries before Meta sends an alert to the developer account.
Of failing messaging deliveries before a Webhooks Disabled alert and the app's unsubscription from the account.
App mode Meta requires before an app receives notifications for its users' accounts.
How does setting up Instagram webhooks work?
In four steps, in the order Meta's guide gives them. The endpoint has to pass verification before any field can be selected, the app has to be Live to receive notifications for its users' accounts, and business verification is required for production access.
What does the verification request contain?
A GET to the callback URL, sent whenever the Webhooks product is configured in the App Dashboard. When hub.verify_token matches the endpoint's own token, the answer is a 200 with the hub.challenge value as the whole body; otherwise a 403. The dashboard reports whether the endpoint passed.
- hub.mode: always subscribe.
- hub.challenge: an integer Meta generates, which the endpoint must send back.
- hub.
verify_token: the string entered in the dashboard's Verify Token field, which only Meta and the endpoint should know. - In PHP, the dots in these names become underscores, so the values arrive as
hub_mode,hub_challengeandhub_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
1158201444Where are the callback and the fields set?
In the App Dashboard, under Instagram, API setup with Instagram login, Configure webhooks: the callback URL and verify token go there, and saving them triggers the verification request. The Instagram product starts subscribed to comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral and messaging_seen, and Manage unsubscribes from any of them. The Test button sends a sample notification for a selected field.
How is X-Hub-Signature-256 checked?
Meta signs each event notification with an HMAC-SHA256 of the payload, keyed with the app's secret, and sends it in X-Hub-Signature-256 as sha256= followed by the hex digest. The receiver computes the same HMAC over the raw request body and compares it, in constant time, with the header. Meta's messaging guide notes that the signature covers the payload with Unicode escaped, so hashing decoded or re-serialized JSON gives a different result.
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);Why can only the app's secret check it?
Because the signature is an HMAC keyed with that secret. Without it, nobody can compute the expected value, and nobody holding a copy of a payload can forge one, so the check belongs on the server that receives Meta's requests for the app. Meta asks that app secrets, access tokens and client credentials stay out of logs and support requests. A system that receives events passed on by another app cannot check Meta's signature at all, and relies on that app's own signature instead.
Why does each account need its own subscription?
Because the App Dashboard sets what the app can receive, and notifications for an account start only once that account is subscribed as well. With Instagram Login, send POST /<IG_ID>/subscribed_apps to graph.instagram.com with the account's Instagram User access token and subscribed_fields listing the fields selected for the app, separated by commas. A successful call returns success set to true.
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }What does Meta do when deliveries fail?
It retries, then gives up. Meta's guide asks for a 200 OK to each notification and warns that batching, up to 1,000 updates, is not guaranteed. A failed update is retried at once, then a few more times with decreasing frequency over 36 hours, and dropped after that, so the same event can arrive twice. Messaging events follow Meta's messaging delivery rules, which act faster:
- A 200 OK is expected within 5 seconds, and a failed delivery gets a few immediate retries, so deduplicate on the message mid.
- After 15 minutes of failures, an alert goes to the developer account.
- After an hour of failures, a Webhooks Disabled alert follows, and the app is unsubscribed from the account's webhooks until it subscribes again.
- Messages sent during an outage can arrive out of order, so sort them by timestamp.
What should you check when nothing arrives?
Meta's troubleshooting checklist, which covers most silent endpoints, in this order:
- The callback URL passed its check and is reachable over HTTPS with a valid certificate; self-signed ones are not supported.
- The app selected the field and has the access level it needs, Advanced Access for comments and
live_comments. - Notifications are enabled for the account through
subscribed_apps, with a token from the same login setup. - The account meets the field's rules: comment notifications need media owned by a public account.
- The server returns success before it starts slow work.
Why does easyCoexistence sign forwarded events again?
Because Meta's signature cannot travel. easyCoexistence's app receives Meta's delivery, checks X-Hub-Signature-256 with its own app secret, answers Meta at once, and POSTs each entry for a connected account to the endpoint set for that account, inside a new body of platform, account_id, external_id and entry. Meta's header is not passed on and could not be checked without that secret, so each forward carries Content-Type: application/json and X-EC-Signature, keyed with a secret that belongs to that one account.
How do you verify X-EC-Signature?
The header reads t=<unix>,v1=<hex>, where v1 is the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the account's signing secret. Recompute it over the bytes exactly as received, compare in constant time, and reject a timestamp more than 5 minutes old.
- The secret starts with whsec_ and is shown once, by
set_social_webhook_destinationor PUT /channels/:id/webhook when the URL is set. - Setting the URL again issues a new secret, and a null URL turns forwarding off.
- Each event is sent once, waiting up to 8 seconds, without following redirects, to an HTTPS address that resolves to a public IP.
- Removing the connection unsubscribes the account from Meta's webhooks and clears its endpoint and secret.
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())Common mistakes
- Returning the challenge as JSON or in quotes. Meta expects the hub.challenge value itself as the body, with a 200 status.
- Hashing a parsed body. A JSON body parser discards the exact bytes Meta signed, so keep the raw body for the HMAC and parse it afterwards.
- Subscribing the app and forgetting the account. Until POST /<IG_ID>/subscribed_apps succeeds for an account, no notifications arrive for it.
- Letting an endpoint fail for an hour. Meta disables messaging webhooks and unsubscribes the app from the account, which then has to be subscribed again.
Turn it on with set_social_webhook_destination or the Partner API. 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
What is hub.challenge in Instagram webhooks?
An integer Meta sends in its verification GET. After checking hub.verify_token, the endpoint returns it as the response body, which proves it controls the URL.
Why are hub.mode and hub.challenge missing in PHP?
PHP turns the dots in parameter names into underscores, so Meta's verification values arrive as hub_mode, hub_challenge and hub_verify_token.
How do I turn Instagram webhooks back on after Meta disables them?
Fix the endpoint, then subscribe the account again with POST /<IG_ID>/subscribed_apps and the same fields.
Does a self-signed certificate work for an Instagram webhook endpoint?
No, Meta does not support self-signed certificates: the callback URL has to be reachable over HTTPS with a valid certificate, the first item on Meta's troubleshooting checklist.
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