Receive and verify Facebook (Meta Graph API) webhooks. Use when setting up Facebook webhook handlers, completing the GET verification handshake, debugging X-Hub-Signature-256 signature verification, or handling Page, Instagram, and Messenger events like feed, mention, comments, and messages.
Receive and verify Facebook (Meta Graph API) webhooks. Use when setting up Facebook webhook handlers, completing the GET verification handshake, debugging X-Hub-Signature-256 signature verification, or handling Page, Instagram, and Messenger events like feed, mention, comments, and messages.
Facebook webhooks are delivered through the Meta Graph API and are shared by
Facebook Pages, Instagram, Messenger, WhatsApp, and other Meta products. They do
not follow the Standard Webhooks spec.
Using WhatsApp? The WhatsApp Business Platform shares this exact Meta
mechanism but has its own events, payloads, and setup — use the dedicated
whatsapp-webhooks
skill. This skill covers Facebook Pages, Instagram, and Messenger. The shared
handshake + X-Hub-Signature-256 algorithm is documented once, canonically, in
references/verification.md.
When to Use This Skill
How do I receive Facebook (Meta Graph API) webhooks?
How do I complete the Facebook GET verification handshake (hub.challenge)?
How do I verify Facebook webhook signatures with X-Hub-Signature-256?
Why is my Facebook webhook signature verification failing?
How do I handle Page feed, mention, Instagram comments, or Messenger messages events?
Two Requests, Two Jobs
Facebook uses one endpoint for two different HTTP methods:
GET — verification handshake (one-time, on registration). Meta sends
hub.mode=subscribe, hub.verify_token, and hub.challenge as query
params. If hub.verify_token matches the Verify Token you set in the App
Dashboard, echo back hub.challenge as a 200 plain-text response.
POST — event delivery. Meta sends a JSON body { object, entry[] }
and signs it with X-Hub-Signature-256.
Verification (core)
Meta signs the raw request body with HMAC-SHA256 keyed on your App
Secret and sends the digest in X-Hub-Signature-256 as sha256=<hex>. Verify
over the raw bytes before JSON parsing — Meta signs an escaped-unicode form
of the payload, so a re-serialized JSON string will not match. (The legacy
X-Hub-Signature header carries SHA-1 — prefer the SHA-256 header.)
A single POST can batch up to 1000 updates across entry[] — always
iterate entry[] and handle each individually.
Messenger deliveries carry a messaging array on each entry instead of
changes.
Respond 200 OK quickly. Failed deliveries are retried immediately, then with
decreasing frequency for up to 36 hours, after which they are dropped.
Important Headers
Header
Description
X-Hub-Signature-256
HMAC SHA-256 of the raw body, sha256=<hex> (use this)
X-Hub-Signature
Legacy HMAC SHA-1 signature (avoid)
Environment Variables
FACEBOOK_APP_SECRET=your_app_secret # App Dashboard → Settings → Basic → App Secret
FACEBOOK_VERIFY_TOKEN=your_verify_token # A string you choose; must match the Dashboard Verify Token
Use the tunnel URL as the Callback URL in App Dashboard → Webhooks. Note:
apps in Development mode only receive test notifications, and Page
subscriptions also require the pages_manage_metadata permission granted via
POST /{page-id}/subscribed_apps.
We recommend installing the webhook-handler-patterns skill alongside this one for handler sequence, idempotency, error handling, and retry logic. Key references (open on GitHub):
Handler sequence — Verify first, parse second, handle idempotently third
Idempotency — Prevent duplicate processing (Meta batches and retries)
Error handling — Return codes, logging, dead letter queues
hookdeck-event-gateway - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers
