WhatsApp Webhook

WhatsApp webhook setup with direct Meta-to-your-server routing

Dualhook helps teams set up a WhatsApp webhook so Meta sends message-path webhooks directly to their own server. That keeps Dualhook out of the inbound message path while still handling setup, Webhook Override, and operational monitoring around the connection.

  • No inbound message proxy
  • Direct Meta webhooks
  • Webhook Override built in

Configure your webhook URL and verify token before Embedded Signup starts, let Dualhook apply Webhook Override automatically, and receive WhatsApp messages directly from Meta with no Dualhook message proxy.

What is a WhatsApp webhook?

A webhook is the HTTPS endpoint that Meta calls when something happens in your WhatsApp Business API or Cloud API setup. Inbound customer messages, delivery and read updates, and other webhook events are delivered as HTTP requests to your server.

Teams usually search for phrases like WhatsApp webhook, WhatsApp API webhook, or WhatsApp Cloud API webhook, even though Meta often uses broader platform terms in its documentation. This page is the plain-language overview of that setup, while the docs cover the payloads and implementation details.

What is Webhook Override and why does it matter?

Dualhook uses Webhook Override so message-path events are routed directly from Meta to your own endpoint. That means the customer endpoint receives the actual message webhooks, while Dualhook's app-level callback remains focused on management events and operational monitoring.

This is the same routing model behind Dualhook's privacy architecture. For the detailed field-level webhook format, see the messaging webhook reference.

How Dualhook sets up the webhook during connection setup

Dualhook asks for this automatically when you click Connect WhatsApp. You do not need to configure the webhook in a separate admin screen first, and Meta does not ask for these values inside the popup itself.

The first step in the connection flow is the setup dialog that collects your webhook URL and verify token before Embedded Signup opens. Those values are then stored on the connection and used during the auto-subscribe step after signup returns, so Webhook Override can be configured before message-path webhooks or imported chat history start landing.

What the setup step looks like

dualhook.com/dashboard/connections
Set up your WhatsApp connection
Configure your webhook endpoint first, then continue to Meta's secure embedded signup.
Connection Name
e.g., Acme Support EU
Webhook URL
https://your-server.com/webhook
Must be HTTPS. Meta will deliver messages and any approved one-time history/contact sync directly to this endpoint.
Verify Token
Enter or generate a verify token
Generate
Use this token in your webhook endpoint to verify Meta's GET handshake requests.
CancelNext

What Dualhook collects automatically in that first step

  • Your HTTPS webhook URL
  • Your webhook verify token
  • A connection name for the setup
Important: Meta does not ask for these values itself. Dualhook collects them first, then uses them later when it calls POST /<WABA_ID>/subscribed_apps on your behalf.

What happens after signup returns

  1. You enter the webhook URL and verify token before Meta opens. In the signup UI, Dualhook asks for your webhookUrl and verifyToken before the Embedded Signup popup starts.

  2. Dualhook stores both values on the connection. Those values become part of the connection configuration so they can be used during the subscribe step after signup returns.

  3. After signup returns and the WABA is known, Dualhook subscribes the app. Dualhook calls POST /<WABA_ID>/subscribed_apps against Meta after the relevant business assets have been discovered.

  4. The payload includes your webhook URL and verify token. Dualhook sends override_callback_uri and verify_token so Meta knows which endpoint to verify and where message-path webhooks should go.

  5. Meta verifies your endpoint with a GET challenge. Meta sends a verification request to your webhook endpoint using the verify token you entered in Dualhook.

  6. If verification succeeds, message webhooks go straight to your endpoint. From that point on, inbound messages and status updates are delivered directly from Meta to your server.

POST /<WABA_ID>/subscribed_apps
{
  "override_callback_uri": "https://your-server.com/webhooks/whatsapp",
  "verify_token": "<the token you entered in Dualhook>"
}

How Meta verifies your webhook endpoint

Meta verifies callback ownership by sending a GET request to your endpoint. Your code needs to compare hub.verify_token with the token you entered in Dualhook. If it matches, return the raw hub.challenge as plain text with HTTP 200. If it does not match, return HTTP 403.

GET /webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=<YOUR_TOKEN>&hub.challenge=1903260781
if request.method == "GET" and query["hub.mode"] == "subscribe":
  if query["hub.verify_token"] == EXPECTED_VERIFY_TOKEN:
    return 200 text/plain query["hub.challenge"]
  else:
    return 403

Common verification failure: returning JSON, quoted strings, HTML, or extra whitespace instead of the raw hub.challenge value. The response body must be the plain challenge string only.

This GET challenge is for your endpoint and uses the per-connection verify token stored on the Dualhook connection. It is separate from Dualhook's own app-level callback verifier, which uses META_WEBHOOK_VERIFY_TOKEN.

What your endpoint must support

  • A public HTTPS URL that Meta can reach from the internet.
  • A GET verification handler for the challenge request.
  • A POST handler for incoming message and status webhooks.
  • Strict envelope, WABA ID, and phone-number ID validation for POST requests.

For the payload shape, delivery guidance, and POST validation details, use the messaging webhook documentation.

Common webhook setup mistakes

  • Using the wrong verify token in your GET verification handler.
  • Returning JSON instead of the raw plain-text challenge.
  • Using a local, private, or otherwise non-public URL.
  • Pointing Meta at the wrong environment URL.
  • Expecting Dualhook to receive and proxy your message webhooks.

Frequently asked questions about WhatsApp webhooks

What is a WhatsApp webhook?

A WhatsApp webhook is the HTTP endpoint that receives inbound messages, delivery updates, and related events from Meta for a WhatsApp Business API or Cloud API setup.

What is Webhook Override in Dualhook?

Webhook Override is the Meta configuration Dualhook uses so message-path webhooks go directly from Meta to your own endpoint instead of through Dualhook's app-level callback.

When do I set the webhook URL and verify token in Dualhook?

Before the Meta Embedded Signup popup opens. Dualhook collects the webhook URL and verify token first, stores them on the connection, and then uses them during the auto-subscribe step after signup completes.

How does Meta verify my webhook endpoint?

Meta sends a GET request with hub.mode=subscribe, hub.verify_token, and hub.challenge. Your endpoint must compare the verify token and, if it matches, return the raw hub.challenge as plain text with HTTP 200.

Does Dualhook store or proxy my WhatsApp messages?

Dualhook does not store message content. Inbound message-path webhooks go directly from Meta to your server. Supported outbound requests transit Dualhook's no-retention runtime without body logging or persistence.

Today