Skip to content

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.

  1. 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.
  2. 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.
  3. Subscribe to the object and fields you need, such as a Page's feed.
terminal
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.

.hooksmith/hooks/meta-page-feed.yaml
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
feed.json
{
  "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.