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

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

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

Frequently asked questions about WhatsApp webhooks