Skip to content

Provider guide

WhatsApp Cloud API webhooks with Hooksmith

WhatsApp Cloud API webhooks are Meta webhooks. When you save the callback URL, Meta sends a GET with hub.verify_token and hub.challenge that must be echoed, and every POST afterwards is signed in X-Hub-Signature-256 with your App Secret. Hooksmith handles both, and the starter hook skips delivery receipts so you only forward real messages.

How WhatsApp signs webhooks

The whatsapp preset uses the same meta verification type as the Meta preset. Only the sourceType and the starter template differ.

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.
  • Delivery receipts are not filtered by the preset itself. The starter hook that hooksmith new --preset whatsapp writes contains a condition that skips requests with a statuses list, and the example below includes it.
  • 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, and 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 WhatsApp, then Configuration, and set the callback URL to the /h/<id> URL that hooksmith deploy printed, with the same verify token.
  3. Subscribe the app to the messages webhook field.
terminal
hooksmith login
hooksmith new whatsapp-inbox --preset whatsapp --yes
# paste the example hook into .hooksmith/hooks/whatsapp-inbox.yaml
hooksmith secrets set META_APP_SECRET
hooksmith secrets set META_VERIFY_TOKEN
hooksmith secrets set DESTINATION_URL
hooksmith test whatsapp-inbox --payload ./message.json
hooksmith deploy whatsapp-inbox   # 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 incoming messages and skip receipts

WhatsApp nests the message under entry, changes and value. This hook forwards the sender, the profile name, the message id and the text, and skips requests that carry delivery statuses instead of messages.

.hooksmith/hooks/whatsapp-inbox.yaml
apiVersion: hooksmith/v1
kind: Hook
metadata:
  name: whatsapp-inbox
  description: Incoming WhatsApp messages to the support inbox
spec:
  source:
    preset: whatsapp
  destinations:
    - name: inbox
      url: ${DESTINATION_URL}
      method: POST
      timeout: 8s
      retries:
        max: 3
        backoff: exponential
        initialDelay: 500ms
  transform:
    engine: handlebars
    fields:
      from: "{{{entry.[0].changes.[0].value.messages.[0].from}}}"
      name: "{{{entry.[0].changes.[0].value.contacts.[0].profile.name}}}"
      message_id: "{{{entry.[0].changes.[0].value.messages.[0].id}}}"
      type: "{{{entry.[0].changes.[0].value.messages.[0].type}}}"
      text: "{{{entry.[0].changes.[0].value.messages.[0].text.body}}}"
  conditions:
    - if: entry[0].changes[0].value.statuses
      then:
        skip: true
  variables:
    - name: META_APP_SECRET
      from: secret
    - name: META_VERIFY_TOKEN
      from: secret
    - name: DESTINATION_URL
      from: secret
message.json
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "contacts": [ { "profile": { "name": "Ada Lovelace" }, "wa_id": "16315551234" } ],
            "messages": [ { "from": "16315551234", "id": "wamid.HBgLMTYzMTU1NTEyMzQ", "type": "text", "text": { "body": "Is the order ready?" } } ]
          }
        }
      ]
    }
  ]
}
  • 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.
  • text is empty for message types other than text, such as images. The type field tells them apart.
  • A Meta hook and a WhatsApp hook in one workspace 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.

What arrives on the messages field

WhatsApp delivers incoming messages and the status of messages you sent through the same messages webhook field. The fields inside value tell them apart.

messages[]
An incoming message, with from, id, type and, for text, text.body.
contacts[]
The sender's profile name and WhatsApp id, next to the message.
statuses[]
A delivery or read receipt for a message you sent. The example skips these.

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 does the WhatsApp webhook verify token work?

You choose any string as the verify token and enter it in the Meta dashboard. When you save the callback URL, Meta sends a GET with hub.mode=subscribe, hub.verify_token and hub.challenge. The endpoint must return the challenge with status 200 if the token matches. Hooksmith does this at GET /h/<id> and compares the token with META_VERIFY_TOKEN. A mismatch gets a 403.

How are WhatsApp webhook payloads signed?

Meta signs each POST with an HMAC-SHA256 of the raw body, keyed with your App Secret, and sends it as X-Hub-Signature-256 (sha256=<hex>). Hooksmith checks it before it stores or processes anything.

Why do I receive webhooks I did not expect when I send messages?

Delivery and read receipts for outgoing messages arrive on the same messages field as incoming ones, in a statuses list. The starter hook skips them with the condition entry[0].changes[0].value.statuses. Remove that condition if you want receipts too.

Why does saving the callback URL in Meta fail?

Meta calls the URL immediately. The hook must already be deployed, META_VERIFY_TOKEN must be stored, and it must equal the token typed in the Meta form exactly. The GET handshake is limited to 30 requests a minute per hook.

Can I test WhatsApp webhooks locally?

Yes, for incoming messages. The desktop app's tunnel replays each stored POST, with its body and X-Hub-Signature-256 header, to a localhost URL. The GET handshake is answered by Hooksmith and not tunneled, so finish the Meta setup first.

Other providers

All providers are listed on webhook providers. Hooks are metered by events processed: see pricing.