{"id":670,"date":"2026-10-29T13:12:29","date_gmt":"2026-10-29T13:12:29","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/whatsapp-api-webhooks\/"},"modified":"2026-10-29T13:12:33","modified_gmt":"2026-10-29T13:12:33","slug":"whatsapp-api-webhooks","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/en\/whatsapp-api-webhooks\/","title":{"rendered":"WhatsApp API webhooks: a practical guide with examples"},"content":{"rendered":"\n

Updated on October 29, 2026<\/em><\/p>\n\n\n\n

A WhatsApp API webhook is an HTTPS URL on your system that receives a POST<\/code> for every event on your account: incoming messages, status changes (sent<\/code>, delivered<\/code>, read<\/code>, failed<\/code>) and account alerts. A well-built endpoint checks where the request came from, returns 200 quickly, puts the event on a queue, processes it in the background and drops duplicates by ID. When you integrate directly with Meta there is also a GET<\/code> verification step; with Vectalk, you register the URL through the API and receive the same payload Meta sends.<\/p>\n\n\n\n

This guide covers the event format, the differences between integrating directly and through Vectalk, and a complete server in Node.js and in Python.<\/p>\n\n\n\n

How the event flow works<\/h2>\n\n\n\n

With a direct integration, Meta calls the endpoint configured in your app. With Vectalk, Meta calls Vectalk, which forwards the event to every active URL registered for that instance:<\/p>\n\n\n\n

Direct:   Meta  \u2500\u2500POST\u2500\u2500\u25b6  your endpoint\nVectalk:  Meta  \u2500\u2500POST\u2500\u2500\u25b6  Vectalk  \u2500\u2500POST\u2500\u2500\u25b6  your URLs (one or several)<\/code><\/pre>\n\n\n\n
The body is the same in both cases. What changes is how the URL is registered and how the request is authenticated.<\/p>\n\n\n\n
Aspect<\/th>Direct Cloud API<\/th>Vectalk<\/th><\/tr><\/thead>
URL setup<\/td>App Dashboard > WhatsApp > Configuration<\/td>POST \/api\/webhooks<\/code> with instance_id<\/code>, url<\/code> and name<\/code><\/td><\/tr>
Endpoint verification<\/td>GET<\/code> with hub.mode<\/code>, hub.verify_token<\/code> and hub.challenge<\/code><\/td>Not described in the Vectalk docs<\/td><\/tr>
Signature<\/td>X-Hub-Signature-256<\/code> header (HMAC-SHA256 with the app secret)<\/td>Not described in the Vectalk docs<\/td><\/tr>
URLs per account<\/td>One endpoint per app (with overrides per messaging account or phone number)<\/td>Several URLs per instance, all receiving the same event<\/td><\/tr>
Response time<\/td>Meta retries if it does not get a 200<\/td>Return 200 in under 20 seconds; otherwise Vectalk resends<\/td><\/tr>
Retries<\/td>Decreasing frequency for up to 7 days<\/td>Resending documented, no time frame given<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Sources: WhatsApp webhooks overview<\/a>, Create a webhook endpoint<\/a> and webhooks in the Vectalk docs<\/a>.<\/p>\n\n\n\n
Registering the webhook with Vectalk<\/h2>\n\n\n\n
curl -X POST https:\/\/apis.vectalk.com.br\/api\/webhooks \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"instance_id\": \"YOUR_INSTANCE_ID\",\n    \"url\": \"https:\/\/myapp.com\/whatsapp\/events\",\n    \"name\": \"Production\"\n  }'<\/code><\/pre>\n\n\n\n
The response includes the webhook id<\/code> and active: true<\/code>. The update endpoint takes that id<\/code> and lets you change the URL, the name or turn the webhook off (active<\/code>); see Register webhook<\/a> and Update webhook<\/a>. The URL must be HTTPS.<\/p>\n\n\n\n
Having several URLs per instance helps in two cases: keeping production and staging apart, and sending the same event to two systems (your CRM and your data warehouse, for example) without building your own fan-out.<\/p>\n\n\n\n
Endpoint verification (direct integration)<\/h2>\n\n\n\n
When you set the webhook in Meta’s App Dashboard (under WhatsApp > Configuration<\/strong>, or Use cases > Customize > Configuration<\/strong> for apps created with the WhatsApp use case), Meta sends a GET<\/code> to your URL with three parameters:<\/p>\n\n\n\n
GET https:\/\/myapp.com\/whatsapp\/events?hub.mode=subscribe&hub.challenge=1158201444&hub.verify_token=my-secret-token<\/code><\/pre>\n\n\n\n
Your endpoint must check that hub.verify_token<\/code> matches the value you entered in the dashboard and return hub.challenge<\/code> in the body with status 200. Any other response fails verification. Meta also requires a valid TLS certificate on the endpoint; self-signed certificates are not supported.<\/p>\n\n\n\n
The payloads you will receive<\/h2>\n\n\n\n
Every event arrives with object: \"whatsapp_business_account\"<\/code> and an entry<\/code> list. Each entry<\/code> has a changes<\/code> list, and each change<\/code> has a field<\/code> and a value<\/code>. For messages and statuses, field<\/code> is messages<\/code>. Other subscribable fields include account_alerts<\/code>, account_update<\/code>, message_template_status_update<\/code>, phone_number_quality_update<\/code> and smb_message_echoes<\/code>.<\/p>\n\n\n\n
Incoming message<\/h3>\n\n\n\n
{\n  \"object\": \"whatsapp_business_account\",\n  \"entry\": [{\n    \"id\": \"WABA_ID\",\n    \"changes\": [{\n      \"field\": \"messages\",\n      \"value\": {\n        \"messaging_product\": \"whatsapp\",\n        \"metadata\": {\n          \"display_phone_number\": \"558430000000\",\n          \"phone_number_id\": \"PHONE_NUMBER_ID\"\n        },\n        \"contacts\": [{\n          \"profile\": { \"name\": \"Jo\u00e3o Silva\" },\n          \"wa_id\": \"5584988888888\",\n          \"user_id\": \"BR.13491208655302741918\"\n        }],\n        \"messages\": [{\n          \"from\": \"5584988888888\",\n          \"from_user_id\": \"BR.13491208655302741918\",\n          \"id\": \"wamid.HBgLNTUx...\",\n          \"timestamp\": \"1760000000\",\n          \"type\": \"text\",\n          \"text\": { \"body\": \"Hi, I'd like more information\" }\n        }]\n      }\n    }]\n  }]\n}<\/code><\/pre>\n\n\n\n
Since April 2026, Meta also sends the BSUID<\/strong> (business-scoped user ID) in contacts[].user_id<\/code> and messages[].from_user_id<\/code>. The phone number is no longer guaranteed: if the customer has turned on a WhatsApp username and none of Meta’s conditions apply (a message or call exchanged with that business number in the last 30 days, or the customer being in your contact book), from<\/code> and wa_id<\/code> are omitted. Don’t use the phone number as your only contact key; the details are in WhatsApp usernames and BSUIDs<\/a>.<\/p>\n\n\n\n
The type<\/code> field tells you where the content is. The most common ones:<\/p>\n\n\n\n
type<\/code><\/th>Where to read<\/th><\/tr><\/thead>
text<\/code><\/td>text.body<\/code><\/td><\/tr>
image<\/code>, video<\/code>, audio<\/code>, document<\/code>, sticker<\/code><\/td><type>.id<\/code> (download through the media endpoint), caption<\/code>, filename<\/code><\/td><\/tr>
interactive<\/code><\/td>interactive.button_reply<\/code> or interactive.list_reply<\/code><\/td><\/tr>
location<\/code><\/td>location.latitude<\/code>, location.longitude<\/code><\/td><\/tr>
reaction<\/code><\/td>reaction.message_id<\/code>, reaction.emoji<\/code><\/td><\/tr>
order<\/code><\/td>order.catalog_id<\/code>, order.product_items[]<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Status of a sent message<\/h3>\n\n\n\n
{\n  \"object\": \"whatsapp_business_account\",\n  \"entry\": [{\n    \"id\": \"WABA_ID\",\n    \"changes\": [{\n      \"field\": \"messages\",\n      \"value\": {\n        \"messaging_product\": \"whatsapp\",\n        \"metadata\": { \"display_phone_number\": \"558430000000\", \"phone_number_id\": \"PHONE_NUMBER_ID\" },\n        \"statuses\": [{\n          \"id\": \"wamid.HBgLNTUx...\",\n          \"status\": \"delivered\",\n          \"timestamp\": \"1760000010\",\n          \"recipient_id\": \"5584988888888\",\n          \"recipient_user_id\": \"BR.13491208655302741918\",\n          \"pricing\": { \"billable\": true, \"pricing_model\": \"PMP\", \"type\": \"regular\", \"category\": \"utility\" }\n        }]\n      }\n    }]\n  }]\n}<\/code><\/pre>\n\n\n\n
The status id<\/code> is the wamid<\/code> you got back when you sent the message. The recipient_user_id<\/code> field carries the customer’s BSUID whether you sent the message to the phone number or to the BSUID; recipient_id<\/code> (the phone number) is omitted when you sent to the BSUID and Meta cannot include the number. Besides sent<\/code>, delivered<\/code>, read<\/code> and failed<\/code>, there is played<\/code> for voice messages. When status<\/code> is failed<\/code>, the object includes errors[]<\/code> with code<\/code>, title<\/code>, message<\/code> and error_data.details<\/code>.<\/p>\n\n\n\n
The pricing<\/code> object carries category<\/code> (marketing<\/code>, utility<\/code>, authentication<\/code>, service<\/code> and others) and type<\/code>: regular<\/code> for billable messages, or a free type such as free_customer_service<\/code> or free_entry_point<\/code>. Since October 1, 2026, utility templates sent inside the customer service window are charged, so they arrive as regular<\/code> instead of free_customer_service<\/code>. Meta has announced that the billable<\/code> field will be deprecated in favor of type<\/code> and category<\/code>. pricing<\/code> comes with the sent<\/code> status and with one of delivered<\/code> or read<\/code>, never with failed<\/code>. Full reference: status webhook documentation<\/a>. For what each category costs, see WhatsApp API pricing in Brazil<\/a> and, for other markets, WhatsApp API pricing by country<\/a>. Status handling is covered in depth in WhatsApp API message status webhooks<\/a>.<\/p>\n\n\n\n
A single POST<\/code> can carry several messages or several statuses: Meta’s webhooks documentation says notifications are batched with up to 1,000 updates per request, though batching is not guaranteed. Iterate over the lists instead of reading only the first item.<\/p>\n\n\n\n
Best practices<\/h2>\n\n\n\n
Return 200 fast and process later<\/h3>\n\n\n\n
The endpoint should not call your database, your AI or another API before responding. Write the raw body to a queue (Redis, SQS, RabbitMQ, an events table) and return 200. A separate worker does the heavy lifting. Vectalk documents a 20-second limit for the response; stay well below it.<\/p>\n\n\n\n
Be idempotent<\/h3>\n\n\n\n
Meta warns that retries can produce duplicate notifications, and a proxy can resend too. Use the message id<\/code> (or the id<\/code> + status<\/code> pair, for statuses) as a unique key. If the key has already been processed, drop the event.<\/p>\n\n\n\n
Validate the signature<\/h3>\n\n\n\n
With a direct integration, Meta signs every POST<\/code> with an HMAC-SHA256 of the body, keyed with your app secret, and sends the result in the X-Hub-Signature-256<\/code> header as sha256=<hash><\/code>. Compute the hash over the raw body<\/strong>, before any JSON parsing, and compare in constant time; the step-by-step guide is in how to validate the WhatsApp webhook signature<\/a>. Webhooks also support mutual TLS (mTLS). Avoid IP allowlists as your only defense: Meta changes its IP addresses periodically and recommends mTLS instead.<\/p>\n\n\n\n
With Vectalk, use the authentication mechanism Vectalk specifies for forwarded requests (check the docs or the contact page<\/a>). Until that is set up in your environment, use a hard-to-guess URL path, keep the endpoint HTTPS-only, and do not trust the content for sensitive actions without checking the expected phone_number_id<\/code>.<\/p>\n\n\n\n
Don’t depend on order<\/h3>\n\n\n\n
Retries mean an older status can arrive after a newer one, and when a message is read right away Meta sends read<\/code> without a delivered<\/code> webhook. Store the most advanced status and the timestamp<\/code> of each step, without ever moving backward.<\/p>\n\n\n\n
Plan for large payloads<\/h3>\n\n\n\n
Meta says webhook payloads can be up to 3 MB. Raise your server’s body size limit accordingly (Express defaults to 100 kb).<\/p>\n\n\n\n
Monitor<\/h3>\n\n\n\n
Track how many events arrive per minute and how many fail in the worker. A sudden drop in message events is often the first sign of a disabled webhook, an expired certificate or a disconnected number.<\/p>\n\n\n\n
Complete example in Node.js (Express)<\/h2>\n\n\n\n
import express from 'express'\nimport crypto from 'node:crypto'\nimport { createClient } from 'redis'\n\nconst app = express()\nconst redis = createClient({ url: process.env.REDIS_URL })\nawait redis.connect()\n\nconst VERIFY_TOKEN = process.env.WHATSAPP_VERIFY_TOKEN \/\/ direct integration\nconst APP_SECRET = process.env.META_APP_SECRET        \/\/ direct integration\n\n\/\/ Keep the raw body so the signature can be validated\napp.use('\/whatsapp\/events', express.raw({ type: 'application\/json', limit: '3mb' }))\n\n\/\/ Endpoint verification (direct integration with Meta only)\napp.get('\/whatsapp\/events', (req, res) => {\n  const { 'hub.mode': mode, 'hub.verify_token': token, 'hub.challenge': challenge } = req.query\n  if (mode === 'subscribe' && token === VERIFY_TOKEN) return res.status(200).send(challenge)\n  return res.sendStatus(403)\n})\n\nfunction validSignature(req) {\n  const header = req.get('X-Hub-Signature-256') || ''\n  const expected = 'sha256=' + crypto.createHmac('sha256', APP_SECRET).update(req.body).digest('hex')\n  const a = Buffer.from(header)\n  const b = Buffer.from(expected)\n  return a.length === b.length && crypto.timingSafeEqual(a, b)\n}\n\napp.post('\/whatsapp\/events', async (req, res) => {\n  if (APP_SECRET && !validSignature(req)) return res.sendStatus(401)\n  await redis.lPush('whatsapp:events', req.body.toString('utf8'))\n  res.sendStatus(200)\n})\n\napp.listen(3000)<\/code><\/pre>\n\n\n\n
And the worker, which consumes the queue and drops duplicates:<\/p>\n\n\n\n
\/\/ uses a Redis client connected the same way as above\nasync function processEvent(event) {\n  for (const entry of event.entry ?? []) {\n    for (const change of entry.changes ?? []) {\n      const v = change.value ?? {}\n      for (const msg of v.messages ?? []) {\n        const isNew = await redis.set(`wa:msg:${msg.id}`, '1', { NX: true, EX: 60 * 60 * 24 * 8 })\n        if (!isNew) continue \/\/ duplicate\n        await handleMessage(v.metadata.phone_number_id, msg, v.contacts) \/\/ your business logic\n      }\n      for (const st of v.statuses ?? []) {\n        const isNew = await redis.set(`wa:st:${st.id}:${st.status}`, '1', { NX: true, EX: 60 * 60 * 24 * 8 })\n        if (!isNew) continue\n        await updateStatus(st) \/\/ store status, errors and pricing\n      }\n    }\n  }\n}\n\nwhile (true) {\n  const item = await redis.brPop('whatsapp:events', 0)\n  try {\n    await processEvent(JSON.parse(item.element))\n  } catch (err) {\n    console.error('failed to process event', err)\n    await redis.lPush('whatsapp:events:error', item.element)\n  }\n}<\/code><\/pre>\n\n\n\n
The eight-day expiry on the keys covers Meta’s retry window, which lasts up to seven days.<\/p>\n\n\n\n
Complete example in Python (FastAPI)<\/h2>\n\n\n\n
import hashlib, hmac, json, os\nimport redis.asyncio as redis\nfrom fastapi import FastAPI, Request, Response\n\napp = FastAPI()\nr = redis.from_url(os.environ[\"REDIS_URL\"])\nVERIFY_TOKEN = os.environ.get(\"WHATSAPP_VERIFY_TOKEN\")  # direct integration\nAPP_SECRET = os.environ.get(\"META_APP_SECRET\", \"\")      # direct integration\n\n\n@app.get(\"\/whatsapp\/events\")\nasync def verify(request: Request):\n    q = request.query_params\n    if q.get(\"hub.mode\") == \"subscribe\" and q.get(\"hub.verify_token\") == VERIFY_TOKEN:\n        return Response(content=q.get(\"hub.challenge\", \"\"), media_type=\"text\/plain\")\n    return Response(status_code=403)\n\n\ndef valid_signature(body: bytes, header: str) -> bool:\n    expected = \"sha256=\" + hmac.new(APP_SECRET.encode(), body, hashlib.sha256).hexdigest()\n    return hmac.compare_digest(expected, header or \"\")\n\n\n@app.post(\"\/whatsapp\/events\")\nasync def receive(request: Request):\n    body = await request.body()\n    if APP_SECRET and not valid_signature(body, request.headers.get(\"X-Hub-Signature-256\")):\n        return Response(status_code=401)\n    await r.lpush(\"whatsapp:events\", body)\n    return Response(status_code=200)<\/code><\/pre>\n\n\n\n
Python worker:<\/p>\n\n\n\n
import asyncio, json, os\nimport redis.asyncio as redis\n\nr = redis.from_url(os.environ[\"REDIS_URL\"])\nEIGHT_DAYS = 60 * 60 * 24 * 8\n\n\nasync def process_event(event: dict):\n    for entry in event.get(\"entry\", []):\n        for change in entry.get(\"changes\", []):\n            v = change.get(\"value\", {})\n            for msg in v.get(\"messages\", []):\n                if not await r.set(f\"wa:msg:{msg['id']}\", 1, nx=True, ex=EIGHT_DAYS):\n                    continue\n                await handle_message(v[\"metadata\"][\"phone_number_id\"], msg, v.get(\"contacts\", []))\n            for st in v.get(\"statuses\", []):\n                if not await r.set(f\"wa:st:{st['id']}:{st['status']}\", 1, nx=True, ex=EIGHT_DAYS):\n                    continue\n                await update_status(st)\n\n\nasync def main():\n    while True:\n        _, item = await r.brpop(\"whatsapp:events\")\n        try:\n            await process_event(json.loads(item))\n        except Exception as exc:\n            print(\"failed to process event\", exc)\n            await r.lpush(\"whatsapp:events:error\", item)\n\nasyncio.run(main())<\/code><\/pre>\n\n\n\n
The handle_message<\/code> and update_status<\/code> functions (and their Node equivalents) are your business logic: reply, write to the CRM, trigger an agent. Inside them, identify the contact by msg.from_user_id<\/code> (or contacts[].user_id<\/code>) and use msg.from<\/code> only when it is present.<\/p>\n\n\n\n
What to do with each event type in the worker<\/h2>\n\n\n\n
Splitting handling by event type makes the worker easier to maintain. A split that works well:<\/p>\n\n\n\n