Messenger webhook for Facebook Pages: messages and mention events
The messages field of Facebook's Page webhooks fires when a person sends the Page a Messenger message, delivering a messaging array with the sender's Page-scoped ID, the Page's ID, a timestamp and the message's mid with its text or attachments. The mention field reports new mentions of the Page in posts and comments, and Meta signs both with X-Hub-Signature-256.
easyCoexistence forwards each connected Page's Messenger messages and mentions to your HTTPS endpoint as they arrive, signed with a secret for that Page and with no copy kept, and send_social_dm replies inside the 24-hour window.
How quickly Meta asks a Messenger webhook endpoint to answer each notification with 200 OK.
After deliveries fail this long, Meta unsubscribes the app from the Page's webhooks until it subscribes again.
The sender's Page-scoped ID in a messages event, unique to each person and Page pair.
How Meta's reference marks the sender field of a mention event.
Past webhook notifications cannot be queried later, so a receiver has to store what it needs.
What does the messages field send?
A notification when a person sends the Page a Messenger message. Meta sends text messages or messages with attachments, which can be images, audio, video, files or stickers among other types, and a shared link can arrive as a fallback attachment. A reply to an earlier message carries reply_to with that message's mid, and a quick reply carries its payload.
What does a messages event look like?
Unlike feed changes, a message arrives in a messaging array inside the Page's entry. Each event has sender, the person's Page-scoped ID; recipient, the Page; a timestamp; and message, with its mid and text, or attachments with a type and a payload URL:
{
"object": "page",
"entry": [
{
"id": "<PAGE_ID>",
"time": 1458692752478,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1458692752478,
"message": {
"mid": "<MESSAGE_ID>",
"text": "hello, world!"
}
}
]
}
]
}What does the mention field send?
A change with field mention when the Page is mentioned in a post or a comment, carrying post_id or comment_id, the message, any link, photo or video, and item and verb. Meta warns that some of those post and comment IDs cannot be queried, for lack of permission or for privacy, and its reference marks the sender field as Workplace only, so a mention may arrive without its author.
Which Messenger fields are not forwarded?
easyCoexistence subscribes Pages to messages, not to message_echoes, messaging_postbacks, message_reads or message_deliveries, so messages the Page sends, button taps and read or delivery receipts are not forwarded. A reply sent with send_social_dm returns its own message ID instead.
How do events reach your endpoint?
Meta delivers Page webhooks to the app the Page installed, through one callback URL for the whole app. easyCoexistence checks Meta's X-Hub-Signature-256 on each delivery, answers Meta at once, and forwards each entry for a connected Page to the HTTPS endpoint you set for it, signed with that Page's own secret. Set it with set_social_webhook_destination from Claude or ChatGPT, or with PUT /channels/:id/webhook on the Partner API; the secret is shown once, setting it again issues a new one, and a null URL turns forwarding off.
What does a forwarded event look like?
A POST holding the platform, the account_id that list_social_accounts gives the Page's connection, the Page's ID as external_id, and entry: Meta's entry for the Page, unchanged. sender.id is the recipient_id that send_social_dm takes for a reply inside the 24-hour window:
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793318400000,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1793318399000,
"message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
}
]
}
}How do you verify a forwarded event?
Each forwarded POST carries 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 the Page's signing secret. Compute it over the body exactly as received, compare in constant time, and reject a timestamp more than 5 minutes old.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}Is a delivery retried?
Not by easyCoexistence. Each entry is forwarded once, in memory, with no copy kept to retry from; the forward waits 8 seconds for an answer, does not follow redirects and goes only to an HTTPS address that resolves to a public IP. Meta notes that past notifications cannot be queried later, so store what you need as it arrives. Upstream, Meta retries a failed delivery a few times at once, so the same message can occasionally reach you twice: deduplicate on its mid.
Common mistakes
- Doing the work before answering. Forwarding does not retry, so return a 2xx at once and process the event afterwards.
- Verifying the signature on parsed JSON. Compute the HMAC over the raw body exactly as it arrived.
- Assuming a message always has text. A sticker, an image or a shared link arrives as attachments, with no text field.
- Skipping deduplication. Meta can deliver an event again after a failure, so key on the message mid before acting.
Turn forwarding 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
Which webhook fields does easyCoexistence subscribe a Page to?
messages for Messenger and mention for mentions, beside feed for the Page's posts and comments.
Does a Messenger sticker or image come with text?
No. A sticker, an image or a shared link arrives in attachments, each with a type and a payload URL, and the message carries no text field.
How fast must a Messenger webhook endpoint answer?
With 200 OK within 5 seconds. After 1 hour of failed deliveries, Meta unsubscribes the app from the Page's webhooks.
How do I reply to a forwarded message?
Call send_social_dm with the sender.id from the event as recipient_id, within 24 hours of the person's message.
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