Instagram webhook events: comments, mentions and DMs
Instagram webhook events report activity on a professional account as it happens: new comments, @mentions and DMs. Meta POSTs each one as JSON to the connected app's HTTPS endpoint and retries a failed delivery to it for up to 36 hours. easyCoexistence passes each event on to your endpoint once, signed per account, with no retries. With Instagram Login, mentions arrive inside the comments notification.
How long Meta keeps retrying a failed delivery to the app's endpoint before dropping it.
Most updates Meta batches into one webhook delivery, though it does not guarantee batching.
Flag Meta sets on message events that the account itself sent.
Only media on public accounts triggers comment and mention notifications.
Which events are there?
For a professional account connected with Instagram Login, three kinds of activity arrive as events:
- Comments: a new comment on the account's media, with the comment ID, the author's Instagram-scoped ID and username, the text, and the media ID and type.
- Mentions: with Instagram Login they come inside the comments notification rather than as a field of their own.
- Messages: a DM to the account, with the sender, the recipient, a timestamp and the message itself, including text, attachments and Story replies.
How do the events reach your endpoint?
Meta delivers Instagram webhooks to the app the account connected to. easyCoexistence receives them and passes each one on to the HTTPS endpoint you set for that account, as it arrives, signed with a secret for that account.
Set the endpoint with set_social_webhook_destination from Claude or ChatGPT, or with the Partner API through PUT /channels/:id/webhook. The signing secret is shown once, setting the endpoint again issues a new one, and passing null as the URL turns forwarding off.
What does a delivery look like?
A POST with a JSON body holding the platform, the account_id that list_social_accounts gives the connection, the Instagram account's external_id, and entry: Meta's webhook entry for the event, unchanged. A DM arrives the same way, with a messaging array in place of changes. A new comment looks like this:
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793318400,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}How do you verify a delivery?
Each delivery 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 request body, keyed with the account's signing secret. Compute it over the raw body exactly as received, compare in constant time, and reject a timestamp older than 5 minutes.
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: forwarding passes each event on once, in memory, and keeps no copy to retry from. Answer with a 2xx quickly and do the work afterwards, and store whatever you need when it arrives, since Meta keeps no history of past notifications that can be queried either.
Meta itself retries a failed delivery to the app for up to 36 hours, so the same event can occasionally reach you twice: deduplicate on the comment ID or the message's mid.
What else should a handler check?
A few details in Meta's payloads that trip up a first handler:
is_echo: a message event withis_echoset to true was sent by the account itself, so it needs no reply.- Story replies: a DM that answers a Story carries
reply_towith the Story's ID and URL. - Story mentions: arrive as a message whose attachment type is
story_mention. - time: when Meta sent the notification, not when the comment or message was made; a message's own timestamp sits in its messaging entry.
- Album IDs: comment events do not include them; look the album up with the comment ID.
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.
- Replying to echoes. A message event with is_echo set is one the account sent, and a reply to it starts a loop.
- Skipping deduplication. Meta can deliver the same event again after a failure, so key on the comment ID or the message mid.
easyCoexistence forwards the Instagram account's comments, mentions and DMs to your HTTPS endpoint as they arrive, signed with a secret for that account and with no copy kept on the way. Turn it on with set_social_webhook_destination from Claude or ChatGPT, or with 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 does the time field in an Instagram webhook mean?
When Meta sent the notification, not when the comment or message was made. A DM's own timestamp sits in its messaging entry.
Does Meta retry failed Instagram webhook deliveries?
Yes. Meta retries a failed delivery to the app for up to 36 hours, so the same event can occasionally arrive twice: deduplicate on the comment ID or the message's mid. easyCoexistence passes each event on to your endpoint once, so answer with a 2xx quickly.
How many updates can one Instagram webhook delivery hold?
Up to 1,000 when Meta batches them, though Meta does not guarantee batching. Loop over the whole entry array rather than reading only its first item.
Do mentions have their own event?
Not with Instagram Login. Meta includes mentions in the comments notification, so they arrive on the same path as comments.
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