Provider guide
Meta webhooks with Hooksmith
A Meta webhook has two checks. When you save the callback URL, Meta sends a GET with hub.mode, hub.verify_token and hub.challenge, and the endpoint must echo the challenge if the token matches. After that, every POST carries X-Hub-Signature-256, an HMAC-SHA256 of the body made with your App Secret. Hooksmith does both for Facebook, Instagram and Messenger.
How Meta signs webhooks
Meta webhooks use a subscription handshake and a signature, and Hooksmith implements both on the same /h/<id> URL.
- Handshake
- GET /h/<id>?hub.mode=subscribe&hub.verify_token=…&hub.challenge=…. If the mode is subscribe and the token equals META_VERIFY_TOKEN, Hooksmith answers 200 with the challenge as plain text. Otherwise it answers 403.
- Header
- X-Hub-Signature-256, in the form sha256=<hex>.
- Algorithm
- HMAC-SHA256, hex encoded, compared in constant time.
- What is signed
- The raw request body.
- Key
- Your Meta App Secret (App settings, Basic).
- Replay window
- None. The signature has no timestamp, so there is no tolerance setting.
- The challenge is echoed only if it is 1 to 256 characters from letters, digits, underscore, dot, colon and hyphen. Anything else is rejected.
- The handshake never delivers anything and is not counted as an event. It is limited to 30 requests per minute per hook.
- A hook that does not use the meta verification type answers a GET with 405.
- A failed signature check on a POST answers 401 VERIFICATION_FAILED and stores nothing.
Set it up
Hooksmith turns the provider preset into a hook you own. The signing secret exists before the endpoint does, so store it first, then deploy, then enter the URL in the provider dashboard. Secrets live in your workspace vault and never go in the YAML. Store META_APP_SECRET, META_VERIFY_TOKEN, DESTINATION_URL.
- Choose a verify token: any string. Store it with hooksmith secrets set META_VERIFY_TOKEN. Store the App Secret as META_APP_SECRET. Do both before you save the callback URL, because Meta calls the URL when you save.
- In the Meta App Dashboard, open Webhooks, and set the callback URL to the /h/<id> URL that hooksmith deploy printed, with the same verify token.
- Subscribe to the object and fields you need, such as a Page's feed.
hooksmith login hooksmith new meta-page-feed --preset meta --yes # paste the example hook into .hooksmith/hooks/meta-page-feed.yaml hooksmith secrets set META_APP_SECRET hooksmith secrets set META_VERIFY_TOKEN hooksmith secrets set DESTINATION_URL hooksmith test meta-page-feed --payload ./feed.json hooksmith deploy meta-page-feed # prints the /h/<id> URL
hooksmith new writes the preset's starter hook. Replace its contents with the example below, or edit it by hand. The CLI's built-in test sample is generic, so pass your own payload with --payload; a matching one is in the next section. The command reference is in the docs.
Forward Page feed changes
A Meta request holds an entry array, and each entry has a list of changes. This hook looks at the first change and skips everything that is not a feed change, such as Messenger messaging events.
apiVersion: hooksmith/v1
kind: Hook
metadata:
name: meta-page-feed
description: Page feed changes to the moderation service
spec:
source:
preset: meta
destinations:
- name: moderation
url: ${DESTINATION_URL}
method: POST
timeout: 8s
retries:
max: 3
backoff: exponential
initialDelay: 500ms
transform:
engine: handlebars
fields:
object: "{{{object}}}"
page_id: "{{{entry.[0].id}}}"
item: "{{{entry.[0].changes.[0].value.item}}}"
verb: "{{{entry.[0].changes.[0].value.verb}}}"
conditions:
- if: entry[0].changes[0].field != "feed"
then:
skip: true
variables:
- name: META_APP_SECRET
from: secret
- name: META_VERIFY_TOKEN
from: secret
- name: DESTINATION_URL
from: secret
{
"object": "page",
"entry": [
{ "id": "1234567890", "time": 1760000000, "changes": [ { "field": "feed", "value": { "item": "post", "verb": "add" } } ] }
]
}- DESTINATION_URL is a workspace secret, so the URL stays out of the YAML. Store it with hooksmith secrets set DESTINATION_URL.
- Values use triple braces so quotes, ampersands, apostrophes and equals signs reach your endpoint as typed. With double braces, template output is HTML-escaped.
- A request can hold several entries. The example reads only the first, so use a destination that can take the full body if you need all of them.
- If you run both a Meta hook and a WhatsApp hook in one workspace, they share the secret names META_APP_SECRET and META_VERIFY_TOKEN. For two different Meta apps, use different secret names in each hook's verification block.
Meta objects and fields
You subscribe by object and field in the Meta App Dashboard. The object name arrives in the object field of the body, and each change names its field.
- page / feed
- Posts, comments and reactions on a Facebook Page.
- page / messages
- Messenger messages sent to a Page.
- page / messaging_postbacks
- Button and quick-reply postbacks in Messenger.
- instagram / comments
- Comments on Instagram media.
- instagram / mentions
- Mentions of your Instagram account.
Test against localhost
The Hooksmith desktop app for Mac can tunnel stored events to a server on your machine. In raw mode it replays the original body bytes and the stored provider headers. Proxy headers such as x-forwarded-host are never stored, so they are not replayed. The target must be localhost, 127.0.0.1, [::1] or a *.localhost name. Get it on the download page.
Hooksmith answers the GET hub.challenge handshake itself and does not tunnel it, so complete the handshake in Meta before you start the tunnel.
Questions
How do I answer the Meta hub.challenge request?
Meta sends a GET with hub.mode=subscribe, hub.verify_token and hub.challenge. Return the challenge value as the response body with status 200 if the token matches the one you chose, and an error otherwise. Hooksmith does exactly this at GET /h/<id>, comparing the token with META_VERIFY_TOKEN in constant time. A wrong token gets a 403.
Which secret does Meta sign webhook posts with?
Your app's App Secret, from App settings, Basic. It is the key for the HMAC-SHA256 in X-Hub-Signature-256. The verify token is a different value and is only used in the GET handshake.
Why does saving the Meta webhook fail?
Meta calls the callback URL as soon as you save it. The hook must be deployed already, META_VERIFY_TOKEN must be stored in your workspace, and the token typed in Meta must match it exactly. A mismatch returns 403, and a missing token on the Hooksmith side fails the same way.
Does Hooksmith dedupe Meta webhooks?
No. None of Hooksmith's default dedupe headers is a Meta header, so a repeated delivery is processed again. If your endpoint needs idempotence, keep a stable identifier from the payload in the transformed body.
Can I use the desktop tunnel for Meta webhooks?
The tunnel replays POST events, with the original body and X-Hub-Signature-256, to localhost. The GET handshake is answered by Hooksmith itself and is never tunneled, so complete the handshake first, then start the tunnel.
Other providers
All providers are listed on webhook providers. Hooks are metered by events processed: see pricing.