Receive webhooks

Message body

Instagram sends messaging events as nested JSON: entry, then messaging.
This body is different from the WhatsApp changes and value shape.

{
  "object": "instagram",
  "entry": [
    {
      "id": "17841400000000000",
      "time": 1716300000,
      "messaging": [
        {
          "sender": { "id": "17841400000000001" },
          "recipient": { "id": "17841400000000000" },
          "timestamp": 1716300000,
          "message": {
            "mid": "aWdfZG1...",
            "text": "hello"
          }
        }
      ]
    }
  ]
}

The sender.id is the Instagram-scoped sender id (IGSID).
Pass it back as the recipient.id when you reply.

Comment events

Comments on your posts arrive at the same webhook URL with field set to comments (or live_comments during a live video).
Meta currently delivers comment events in two body shapes. Handle both. Shape 1: changes array (Meta’s self-comment example):

{
  "object": "instagram",
  "entry": [
    {
      "id": "17841400000000000",
      "time": 1716300000,
      "changes": [
        {
          "field": "comments",
          "value": {
            "id": "17900000000000000",
            "text": "Nice post!",
            "from": { "id": "17841400000000001", "username": "commenter" },
            "media": { "id": "17850000000000000", "media_product_type": "FEED" },
            "parent_id": "17890000000000000"
          }
        }
      ]
    }
  ]
}

Shape 2: flat field and value on the entry (Meta’s ordinary-comment example):

{
  "object": "instagram",
  "entry": [
    {
      "id": "17841400000000000",
      "time": 1716300000,
      "field": "comments",
      "value": {
        "id": "17900000000000000",
        "text": "Nice post!",
        "from": { "username": "commenter" },
        "media": { "id": "17850000000000000", "media_product_type": "FEED" }
      }
    }
  ]
}

Treat from.id, parent_id, and fields that only appear on your own comments as optional.
Some deliveries omit from.id entirely, and parent_id is only present on replies.
Comments you post yourself also arrive as events. Check from.username against your own handle if you want to skip your own replies. Mentions of your account arrive inside these same comments events. There is no separate mentions payload to wait for.
Channels are also subscribed to the mentions, story_insights, and message_edit fields (reconnect a channel connected before this to pick the subscription up). To act on a comment event, see Comments.

Other message events

Beyond plain text, the messaging array carries these events. All arrive at the same webhook URL.

Event	Key fields
Media attachments	`message.attachments[]` with `type` (`image`, `video`, `audio`, `file`, `ig_reel`, `reel`) and `payload.url`
Post shared with you	`message.attachments[]` with `type: "ig_post"` and the media id, URL, and title in the payload
Story mention	`message.attachments[]` with `type: "story_mention"` and the story URL in `payload.url`
Disappearing media	`message.attachments[]` with `type: "ephemeral"`, no URL
Reply to your story	`message.reply_to.story` with `url`, `id`, and `link_sticker_url` when the story had a link sticker
Reply to a message	`message.reply_to.mid` with the id of the message being replied to
Reaction	`reaction` with `mid`, `action` (`react` or `unreact`), and the emoji
Message seen	`read` with the `mid` of the last message the person saw
Postback	`postback` with the `title` and `payload` of the ice breaker or menu item tapped
Referral	`referral` with the `ref` and source when someone opens a chat from an ig.me link or an ad
Deleted message	`message.is_deleted: true`
Your own sends	`message.is_echo: true`

Post shares used to arrive with type: "share". Meta replaced it with ig_post, which adds the media id and title.
If your receiver matches on share, switch it to ig_post. A story reply example (one item from entry[].messaging[], not a complete webhook body):

{
  "sender": { "id": "17841400000000001" },
  "recipient": { "id": "17841400000000000" },
  "timestamp": 1716300000,
  "message": {
    "mid": "aWdfZG1...",
    "text": "love this!",
    "reply_to": {
      "story": {
        "url": "https://lookaside.fbsbx.com/...",
        "id": "17900000000000000",
        "link_sticker_url": "https://example.com/promo"
      }
    }
  }
}

Verification GET

When you set a deployed webhook URL, HookMyApp checks that your receiver can answer a verification request.
Respond with VERIFY_TOKEN and HTTP 200.
Local listen commands skip this check because they send DMs to your computer only while the command runs.

app.get('/webhook/instagram', (req, res) => {
  res.send(process.env.VERIFY_TOKEN)
})

Signature verification

Every message delivery POST arrives with X-HookMyApp-Signature-256: sha256=<hex>.
Compute HMAC-SHA256 over the raw request body using WEBHOOK_HMAC_SECRET as the key.
This is the HMAC signing secret from hookmyapp channels env or hookmyapp sandbox env.
It is not the VERIFY_TOKEN.
The VERIFY_TOKEN is only echoed back on the ownership GET probe.
Compare the computed value against the hex digest in the header. One POST is never signed: when you run webhook set, HookMyApp sends an empty-body verification probe marked X-HookMyApp-Probe: webhook-verification (User-Agent HookMyApp-Webhook-Verifier).
Answer it with any 2xx before checking signatures, or verification fails. For more detail, see Meta webhook docs.

import express from 'express'
import { createHmac, timingSafeEqual } from 'node:crypto'

const app = express()
const HMAC_SECRET = process.env.WEBHOOK_HMAC_SECRET
const VERIFY_TOKEN = process.env.VERIFY_TOKEN // only for the GET ownership probe

// Capture the raw body. express.json() would re-serialize and
// break the HMAC comparison.
app.post(
  '/webhook/instagram',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    // The `webhook set` verification probe is unsigned and empty;
    // acknowledge it before the signature check. Match the full probe
    // contract (header + user agent + empty body); anything else falls
    // through to signature verification.
    if (
      req.get('X-HookMyApp-Probe') === 'webhook-verification' &&
      req.get('User-Agent') === 'HookMyApp-Webhook-Verifier' &&
      !req.body?.length
    ) {
      return res.sendStatus(200)
    }

    const signature = req.get('X-HookMyApp-Signature-256') || ''
    const expected = 'sha256=' +
      createHmac('sha256', HMAC_SECRET)
        .update(req.body)
        .digest('hex')

    const a = Buffer.from(signature)
    const b = Buffer.from(expected)
    if (a.length !== b.length || !timingSafeEqual(a, b)) {
      return res.sendStatus(401)
    }

    const payload = JSON.parse(req.body.toString('utf8'))
    // Process payload.entry[...].messaging[...].message
    res.json({ status: 'ok' })
  },
)

Acknowledge fast

Return 200 immediately.
Process asynchronously.
Queue longer work before responding.

Three ways to receive DMs

Listen in the sandbox: hookmyapp sandbox listen --path /webhook/instagram tells HookMyApp to send test Instagram DMs to your local receiver.
Use this with the HookMyApp test Instagram account.
Keep the CLI running while you test.
Listen to your own account locally: hookmyapp channels listen <channel> --path /webhook/instagram tells HookMyApp to send DMs from your connected Instagram account to your local receiver.
Use this to test with your real Instagram account before you deploy.
Stop the CLI when you are done.
Your own account, your own URL: hookmyapp channels webhook set <channel> --url <your-public-https-url> sends DMs to your deployed receiver.
Use this after your receiver is live.

Next steps

Webhook routing: Choose where incoming Instagram DMs are delivered.
Event subscriptions: Send DMs and comments to extra URLs, next to this webhook.
Instagram quickstart: Skip the boilerplate and clone the reference receiver.

Getting started

Sending & receiving

Publish & engage

Tools

API Reference

Message body

Comment events

Other message events

Verification GET

Signature verification

Acknowledge fast

Three ways to receive DMs

Next steps

​Message body

​Comment events

​Other message events

​Verification GET

​Signature verification

​Acknowledge fast

​Three ways to receive DMs

​Next steps

Message body

Comment events

Other message events

Verification GET

Signature verification

Acknowledge fast

Three ways to receive DMs

Next steps