{"id":671,"date":"2026-10-29T13:12:30","date_gmt":"2026-10-29T13:12:30","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/webhooks-api-whatsapp\/"},"modified":"2026-10-29T13:12:39","modified_gmt":"2026-10-29T13:12:39","slug":"webhooks-api-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/es\/webhooks-api-whatsapp\/","title":{"rendered":"Webhooks de la API de WhatsApp: gu\u00eda pr\u00e1ctica con ejemplos"},"content":{"rendered":"\n

Actualizado el 29\/10\/2026<\/em><\/p>\n\n\n\n

Un webhook de la API de WhatsApp es una URL HTTPS de tu sistema que recibe, por POST<\/code>, cada evento de la cuenta: mensajes recibidos, cambios de estado (sent<\/code>, delivered<\/code>, read<\/code>, failed<\/code>) y alertas de la cuenta. Un endpoint bien hecho valida el origen de la solicitud, responde 200 en pocos segundos, pone el evento en una cola, lo procesa en segundo plano y descarta los duplicados por ID. En la integraci\u00f3n directa con Meta tambi\u00e9n hay un paso de verificaci\u00f3n por GET<\/code>; con Vectalk, la URL se registra por API y recibe el mismo payload que env\u00eda Meta.<\/p>\n\n\n\n

Esta gu\u00eda muestra el formato de los eventos, las diferencias entre integrar directo y a trav\u00e9s de Vectalk, y un servidor completo en Node.js y en Python.<\/p>\n\n\n\n

C\u00f3mo funciona el flujo de eventos<\/h2>\n\n\n\n

En la integraci\u00f3n directa, Meta llama al endpoint configurado en tu app. Con Vectalk, Meta llama a Vectalk, que reenv\u00eda el evento a todas las URLs activas registradas para esa instancia:<\/p>\n\n\n\n

Directo:  Meta  \u2500\u2500POST\u2500\u2500\u25b6  tu endpoint\nVectalk:  Meta  \u2500\u2500POST\u2500\u2500\u25b6  Vectalk  \u2500\u2500POST\u2500\u2500\u25b6  tus URLs (una o varias)<\/code><\/pre>\n\n\n\n
El cuerpo es el mismo en los dos casos. Lo que cambia es c\u00f3mo se registra la URL y c\u00f3mo se autentica la solicitud.<\/p>\n\n\n\n
Aspecto<\/th>Cloud API directa<\/th>Vectalk<\/th><\/tr><\/thead>
Registro de la URL<\/td>Panel de apps > WhatsApp > Configuraci\u00f3n<\/td>POST \/api\/webhooks<\/code> con instance_id<\/code>, url<\/code> y name<\/code><\/td><\/tr>
Verificaci\u00f3n del endpoint<\/td>GET<\/code> con hub.mode<\/code>, hub.verify_token<\/code> y hub.challenge<\/code><\/td>No descrita en la documentaci\u00f3n de Vectalk<\/td><\/tr>
Firma<\/td>Header X-Hub-Signature-256<\/code> (HMAC-SHA256 con el secreto de la app)<\/td>No descrita en la documentaci\u00f3n de Vectalk<\/td><\/tr>
URLs por cuenta<\/td>Un endpoint por app (con reemplazos por cuenta de mensajes o por n\u00famero)<\/td>Varias URLs por instancia, todas reciben el mismo evento<\/td><\/tr>
Tiempo de respuesta<\/td>Meta reintenta si no recibe 200<\/td>Responder 200 en menos de 20 segundos; si no, Vectalk reenv\u00eda<\/td><\/tr>
Reintentos<\/td>Frecuencia decreciente durante hasta 7 d\u00edas<\/td>Reenv\u00edo documentado, sin plazo informado<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Fuentes: descripci\u00f3n general de webhooks de WhatsApp<\/a>, crear un endpoint de webhook<\/a> y webhooks en la documentaci\u00f3n de Vectalk<\/a>.<\/p>\n\n\n\n
C\u00f3mo registrar el webhook en Vectalk<\/h2>\n\n\n\n
curl -X POST https:\/\/apis.vectalk.com.br\/api\/webhooks \\\n  -H \"Authorization: Bearer TU_TOKEN\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"instance_id\": \"TU_INSTANCE_ID\",\n    \"url\": \"https:\/\/miapp.com\/whatsapp\/eventos\",\n    \"name\": \"Producci\u00f3n\"\n  }'<\/code><\/pre>\n\n\n\n
La respuesta trae el id<\/code> del webhook y active: true<\/code>. El endpoint de actualizaci\u00f3n recibe ese id<\/code> y te permite cambiar la URL, el nombre o desactivar el webhook (active<\/code>); consulta Registrar webhook<\/a> y Actualizar webhook<\/a>. La URL tiene que ser HTTPS.<\/p>\n\n\n\n
Tener varias URLs por instancia sirve en dos casos: separar producci\u00f3n y pruebas, y enviar el mismo evento a dos sistemas (el CRM y el data warehouse, por ejemplo) sin armar un reenv\u00edo propio.<\/p>\n\n\n\n
Verificaci\u00f3n del endpoint (integraci\u00f3n directa)<\/h2>\n\n\n\n
Cuando configuras el webhook en el panel de apps de Meta (en WhatsApp > Configuraci\u00f3n<\/strong>, o en Casos de uso > Personalizar > Configuraci\u00f3n<\/strong> si la app se cre\u00f3 con el caso de uso de WhatsApp), Meta hace un GET<\/code> a tu URL con tres par\u00e1metros:<\/p>\n\n\n\n
GET https:\/\/miapp.com\/whatsapp\/eventos?hub.mode=subscribe&hub.challenge=1158201444&hub.verify_token=mi-token-secreto<\/code><\/pre>\n\n\n\n
El endpoint debe comprobar que hub.verify_token<\/code> sea igual al valor que definiste en el panel y devolver hub.challenge<\/code> en el cuerpo, con estado 200. Cualquier otra respuesta hace fallar la verificaci\u00f3n. Meta tambi\u00e9n exige un certificado TLS v\u00e1lido en el endpoint; no acepta certificados autofirmados.<\/p>\n\n\n\n
Los payloads que vas a recibir<\/h2>\n\n\n\n
Todo evento llega con object: \"whatsapp_business_account\"<\/code> y una lista entry<\/code>. Cada entry<\/code> tiene una lista changes<\/code>, y cada change<\/code> tiene field<\/code> y value<\/code>. Para mensajes y estados, field<\/code> es messages<\/code>. Otros campos suscribibles son, por ejemplo, account_alerts<\/code>, account_update<\/code>, message_template_status_update<\/code>, phone_number_quality_update<\/code> y smb_message_echoes<\/code>.<\/p>\n\n\n\n
Mensaje recibido<\/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\": \"Hola, quiero m\u00e1s informaci\u00f3n\" }\n        }]\n      }\n    }]\n  }]\n}<\/code><\/pre>\n\n\n\n
Desde abril de 2026, Meta tambi\u00e9n env\u00eda el BSUID<\/strong> (ID de usuario con alcance de empresa) en contacts[].user_id<\/code> y messages[].from_user_id<\/code>. El n\u00famero de tel\u00e9fono ya no est\u00e1 garantizado: si el cliente activ\u00f3 un nombre de usuario de WhatsApp y no se cumple ninguna de las condiciones de Meta (un mensaje o llamada intercambiados con ese n\u00famero de la empresa en los \u00faltimos 30 d\u00edas, o que el cliente est\u00e9 en tu libreta de contactos), from<\/code> y wa_id<\/code> se omiten. No uses el tel\u00e9fono como \u00fanica clave del contacto; los detalles est\u00e1n en nombres de usuario de WhatsApp y BSUID<\/a>.<\/p>\n\n\n\n
El campo type<\/code> indica d\u00f3nde est\u00e1 el contenido. Los m\u00e1s comunes:<\/p>\n\n\n\n
type<\/code><\/th>D\u00f3nde leer<\/th><\/tr><\/thead>
text<\/code><\/td>text.body<\/code><\/td><\/tr>
image<\/code>, video<\/code>, audio<\/code>, document<\/code>, sticker<\/code><\/td><tipo>.id<\/code> (descarga por el endpoint de multimedia), caption<\/code>, filename<\/code><\/td><\/tr>
interactive<\/code><\/td>interactive.button_reply<\/code> o 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
Estado de un mensaje enviado<\/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
El id<\/code> del estado es el wamid<\/code> que recibiste al enviar el mensaje. El campo recipient_user_id<\/code> trae el BSUID del cliente, tanto si enviaste el mensaje al n\u00famero como al BSUID; recipient_id<\/code> (el tel\u00e9fono) se omite cuando enviaste al BSUID y Meta no puede incluir el n\u00famero. Adem\u00e1s de sent<\/code>, delivered<\/code>, read<\/code> y failed<\/code>, existe played<\/code> para mensajes de voz. Cuando status<\/code> es failed<\/code>, el objeto trae errors[]<\/code> con code<\/code>, title<\/code>, message<\/code> y error_data.details<\/code>.<\/p>\n\n\n\n
El objeto pricing<\/code> trae category<\/code> (marketing<\/code>, utility<\/code>, authentication<\/code>, service<\/code>, entre otras) y type<\/code>: regular<\/code> para mensajes cobrables, o un tipo gratuito como free_customer_service<\/code> o free_entry_point<\/code>. Desde el 1 de octubre de 2026, las plantillas de utilidad enviadas dentro de la ventana de atenci\u00f3n se cobran, as\u00ed que llegan como regular<\/code> en lugar de free_customer_service<\/code>. Meta anunci\u00f3 que el campo billable<\/code> quedar\u00e1 obsoleto en favor de type<\/code> y category<\/code>. pricing<\/code> llega con el estado sent<\/code> y con uno de delivered<\/code> o read<\/code>, nunca con failed<\/code>. Referencia completa: documentaci\u00f3n del webhook de estado<\/a>. Para saber cu\u00e1nto cuesta cada categor\u00eda, consulta el precio de la API de WhatsApp en Brasil<\/a> y, para otros mercados, el precio de la API de WhatsApp por pa\u00eds<\/a>. El manejo de estados est\u00e1 explicado a fondo en estados de mensaje por webhook en WhatsApp<\/a>.<\/p>\n\n\n\n
Un mismo POST<\/code> puede traer varios mensajes o varios estados: seg\u00fan la documentaci\u00f3n de webhooks de Meta, las notificaciones se agrupan con hasta 1.000 actualizaciones por solicitud, aunque el agrupamiento no est\u00e1 garantizado. Recorre las listas en lugar de leer solo el primer elemento.<\/p>\n\n\n\n
Buenas pr\u00e1cticas<\/h2>\n\n\n\n
Responde 200 r\u00e1pido y procesa despu\u00e9s<\/h3>\n\n\n\n
El endpoint no debe llamar a tu base de datos, a la IA ni a otra API antes de responder. Guarda el cuerpo crudo en una cola (Redis, SQS, RabbitMQ, una tabla de eventos) y devuelve 200. Un worker aparte hace el trabajo pesado. Vectalk documenta un l\u00edmite de 20 segundos para la respuesta; mantente muy por debajo.<\/p>\n\n\n\n
S\u00e9 idempotente<\/h3>\n\n\n\n
Meta advierte que los reintentos pueden duplicar notificaciones, y un proxy tambi\u00e9n puede reenviar. Usa el id<\/code> del mensaje (o la combinaci\u00f3n id<\/code> + status<\/code>, en el caso de los estados) como clave \u00fanica. Si la clave ya se proces\u00f3, descarta el evento.<\/p>\n\n\n\n
Valida la firma<\/h3>\n\n\n\n
En la integraci\u00f3n directa, Meta firma cada POST<\/code> con un HMAC-SHA256 del cuerpo, usando el secreto de tu app, y env\u00eda el resultado en el header X-Hub-Signature-256<\/code> con el formato sha256=<hash><\/code>. Calcula el hash sobre el cuerpo crudo<\/strong>, antes de cualquier parseo de JSON, y compara en tiempo constante; el paso a paso est\u00e1 en c\u00f3mo validar la firma del webhook de WhatsApp<\/a>. Los webhooks tambi\u00e9n admiten TLS mutuo (mTLS). No dependas solo de una lista de IPs permitidas: Meta cambia sus direcciones IP peri\u00f3dicamente y recomienda mTLS en su lugar.<\/p>\n\n\n\n
Con Vectalk, usa el mecanismo de autenticaci\u00f3n que Vectalk indique para las solicitudes reenviadas (consulta la documentaci\u00f3n o la p\u00e1gina de contacto<\/a>). Mientras eso no est\u00e9 configurado en tu entorno, usa una ruta de URL dif\u00edcil de adivinar, limita el endpoint a HTTPS y no conf\u00edes en el contenido para acciones sensibles sin verificar el phone_number_id<\/code> esperado.<\/p>\n\n\n\n
No dependas del orden<\/h3>\n\n\n\n
Por los reintentos, un estado antiguo puede llegar despu\u00e9s de uno m\u00e1s nuevo, y cuando un mensaje se lee enseguida Meta env\u00eda read<\/code> sin webhook de delivered<\/code>. Guarda el estado m\u00e1s avanzado y el timestamp<\/code> de cada etapa, sin retroceder nunca.<\/p>\n\n\n\n
Prep\u00e1rate para payloads grandes<\/h3>\n\n\n\n
Meta informa que los payloads de webhook pueden tener hasta 3 MB. Ajusta el l\u00edmite de cuerpo de tu servidor (el predeterminado de Express es 100 kb).<\/p>\n\n\n\n
Monitorea<\/h3>\n\n\n\n
Registra cu\u00e1ntos eventos llegan por minuto y cu\u00e1ntos fallan en el worker. Una ca\u00edda brusca de eventos de mensajes suele ser la primera se\u00f1al de un webhook desactivado, un certificado vencido o un n\u00famero desconectado.<\/p>\n\n\n\n
Ejemplo completo en 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 \/\/ integraci\u00f3n directa\nconst APP_SECRET = process.env.META_APP_SECRET        \/\/ integraci\u00f3n directa\n\n\/\/ Guarda el cuerpo crudo para validar la firma\napp.use('\/whatsapp\/eventos', express.raw({ type: 'application\/json', limit: '3mb' }))\n\n\/\/ Verificaci\u00f3n del endpoint (solo en la integraci\u00f3n directa con Meta)\napp.get('\/whatsapp\/eventos', (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 firmaValida(req) {\n  const header = req.get('X-Hub-Signature-256') || ''\n  const esperado = 'sha256=' + crypto.createHmac('sha256', APP_SECRET).update(req.body).digest('hex')\n  const a = Buffer.from(header)\n  const b = Buffer.from(esperado)\n  return a.length === b.length && crypto.timingSafeEqual(a, b)\n}\n\napp.post('\/whatsapp\/eventos', async (req, res) => {\n  if (APP_SECRET && !firmaValida(req)) return res.sendStatus(401)\n  await redis.lPush('whatsapp:eventos', req.body.toString('utf8'))\n  res.sendStatus(200)\n})\n\napp.listen(3000)<\/code><\/pre>\n\n\n\n
Y el worker, que consume la cola y descarta duplicados:<\/p>\n\n\n\n
\/\/ usa un cliente Redis conectado igual que arriba\nasync function procesar(evento) {\n  for (const entry of evento.entry ?? []) {\n    for (const change of entry.changes ?? []) {\n      const v = change.value ?? {}\n      for (const msg of v.messages ?? []) {\n        const nuevo = await redis.set(`wa:msg:${msg.id}`, '1', { NX: true, EX: 60 * 60 * 24 * 8 })\n        if (!nuevo) continue \/\/ duplicado\n        await tratarMensaje(v.metadata.phone_number_id, msg, v.contacts) \/\/ tu l\u00f3gica de negocio\n      }\n      for (const st of v.statuses ?? []) {\n        const nuevo = await redis.set(`wa:st:${st.id}:${st.status}`, '1', { NX: true, EX: 60 * 60 * 24 * 8 })\n        if (!nuevo) continue\n        await actualizarEstado(st) \/\/ guarda estado, errores y pricing\n      }\n    }\n  }\n}\n\nwhile (true) {\n  const item = await redis.brPop('whatsapp:eventos', 0)\n  try {\n    await procesar(JSON.parse(item.element))\n  } catch (err) {\n    console.error('error al procesar evento', err)\n    await redis.lPush('whatsapp:eventos:error', item.element)\n  }\n}<\/code><\/pre>\n\n\n\n
La expiraci\u00f3n de ocho d\u00edas en las claves cubre la ventana de reintentos de Meta, que llega a siete d\u00edas.<\/p>\n\n\n\n
Ejemplo completo en 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\")  # integraci\u00f3n directa\nAPP_SECRET = os.environ.get(\"META_APP_SECRET\", \"\")      # integraci\u00f3n directa\n\n\n@app.get(\"\/whatsapp\/eventos\")\nasync def verificar(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 firma_valida(cuerpo: bytes, header: str) -> bool:\n    esperado = \"sha256=\" + hmac.new(APP_SECRET.encode(), cuerpo, hashlib.sha256).hexdigest()\n    return hmac.compare_digest(esperado, header or \"\")\n\n\n@app.post(\"\/whatsapp\/eventos\")\nasync def recibir(request: Request):\n    cuerpo = await request.body()\n    if APP_SECRET and not firma_valida(cuerpo, request.headers.get(\"X-Hub-Signature-256\")):\n        return Response(status_code=401)\n    await r.lpush(\"whatsapp:eventos\", cuerpo)\n    return Response(status_code=200)<\/code><\/pre>\n\n\n\n
Worker en Python:<\/p>\n\n\n\n
import asyncio, json, os\nimport redis.asyncio as redis\n\nr = redis.from_url(os.environ[\"REDIS_URL\"])\nOCHO_DIAS = 60 * 60 * 24 * 8\n\n\nasync def procesar(evento: dict):\n    for entry in evento.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=OCHO_DIAS):\n                    continue\n                await tratar_mensaje(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=OCHO_DIAS):\n                    continue\n                await actualizar_estado(st)\n\n\nasync def main():\n    while True:\n        _, item = await r.brpop(\"whatsapp:eventos\")\n        try:\n            await procesar(json.loads(item))\n        except Exception as exc:\n            print(\"error al procesar evento\", exc)\n            await r.lpush(\"whatsapp:eventos:error\", item)\n\nasyncio.run(main())<\/code><\/pre>\n\n\n\n
Las funciones tratar_mensaje<\/code> y actualizar_estado<\/code> (y sus equivalentes en Node) son tu l\u00f3gica de negocio: responder, guardar en el CRM, activar un agente. Dentro de ellas, identifica al contacto por msg.from_user_id<\/code> (o contacts[].user_id<\/code>) y usa msg.from<\/code> solo cuando est\u00e9 presente.<\/p>\n\n\n\n
Qu\u00e9 hacer con cada tipo de evento en el worker<\/h2>\n\n\n\n
Separar el tratamiento por tipo de evento hace que el worker sea m\u00e1s f\u00e1cil de mantener. Una divisi\u00f3n que funciona bien:<\/p>\n\n\n\n