Cómo configurar webhooks de WhatsApp Business: guía técnica 2026

Configurar webhooks de WhatsApp Business en 2026 requiere una callback URL HTTPS pública, un verify token para handshake con Meta, lógica para procesar los eventos JSON entrantes (mensajes, status, plantillas, business_capability) y manejo de retries. Para empresas con equipo de ingeniería es el camino para máxima flexibilidad; para todos los demás, una plataforma como Aurora Inbox absorbe toda la complejidad y deja webhooks de aplicación específicos cuando son necesarios.

Qué es un webhook de WhatsApp Business

Un webhook es un endpoint HTTPS público al que Meta hace POST cada vez que ocurre un evento en tu cuenta de WhatsApp Business: mensaje entrante, cambio de status (entregado, leído), aprobación de plantilla, cambio de calidad del número.

Sin webhooks, no hay forma de saber lo que pasa en tu API. Son la forma "push" en la que Meta te notifica.

Tipos de eventos de webhook

Meta envía cinco categorías de eventos:

Evento Cuándo se dispara Caso de uso
messages Cliente envía mensaje Procesar el mensaje y responder
statuses Cambio de estado de un mensaje saliente Tracking de delivery, read
template_status_update Plantilla aprobada/rechazada/pausada Actualizar tu UI de plantillas
business_capability_update Cambios en tier, calidad o capacidades Alertas tempranas de problemas
phone_number_quality_update Cambios en calidad verde/amarilla/roja Reaccionar antes del baneo

Configurar webhook con Cloud API directa

Paso 1: Tener callback URL HTTPS pública

Tu servidor debe ser:

  • HTTPS con certificado válido (Meta rechaza HTTP).
  • Pública (no localhost, no IP interna).
  • Endpoint específico para webhook (ej. https://tu-dominio.com/webhooks/whatsapp).

Para desarrollo local, ngrok o tunnels similares funcionan.

Paso 2: Implementar handshake de verificación

Meta envía GET inicial para verificar tu callback URL:

GET /webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=TU_TOKEN&hub.challenge=12345

Tu servidor debe:

  1. Validar que hub.verify_token coincide con el token que registraste.
  2. Devolver hub.challenge como respuesta plana.

Ejemplo en Node.js Express:

app.get('/webhooks/whatsapp', (req, res) => {
  if (req.query['hub.verify_token'] === process.env.WHATSAPP_VERIFY_TOKEN) {
    res.send(req.query['hub.challenge']);
  } else {
    res.status(403).send('Forbidden');
  }
});

Paso 3: Procesar eventos POST

Una vez verificado, Meta hace POST con el evento:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { ... },
        "messages": [{
          "from": "521234567890",
          "id": "wamid.xxxxx",
          "timestamp": "1716000000",
          "text": { "body": "Hola, ¿cuánto cuesta?" },
          "type": "text"
        }]
      },
      "field": "messages"
    }]
  }]
}

Tu servidor debe:

app.post('/webhooks/whatsapp', (req, res) => {
  const entry = req.body.entry[0].changes[0].value;
  if (entry.messages) {
    for (const msg of entry.messages) {
      processIncomingMessage(msg);
    }
  }
  if (entry.statuses) {
    for (const status of entry.statuses) {
      updateMessageStatus(status);
    }
  }
  res.sendStatus(200); // CRÍTICO: responde 200 rápido
});

Paso 4: Configurar webhook en Meta App

En Meta App Dashboard:

  1. WhatsApp → Configuration → Webhook.
  2. Callback URL: https://tu-dominio.com/webhooks/whatsapp.
  3. Verify Token: la cadena que tu código compara.
  4. Subscribe to fields: messages, message_template_status_update, etc.
  5. Click Verify and Save. Si tu handshake funciona, queda registrado.

Paso 5: Validar firma de seguridad

Meta firma cada POST con HMAC-SHA256. Valida la firma para evitar requests falsos:

const crypto = require('crypto');
function verifySignature(req) {
  const signature = req.headers['x-hub-signature-256'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WHATSAPP_APP_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');
  return signature === expected;
}

Manejo de errores y retries

Meta reintenta el POST si tu servidor:

  • Devuelve código diferente a 200.
  • No responde en 5 segundos.

Buenas prácticas:

  • Responde 200 inmediatamente y procesa la lógica en background con una cola.
  • Idempotencia. Cada evento tiene un wamid único — si recibes duplicados, no proceses dos veces.
  • Logging completo de payload entrante para debugging.
  • Alertas si la tasa de error sube.

Errores comunes en configuración de webhook

  • HTTP en lugar de HTTPS — Meta rechaza.
  • Certificado SSL inválido — Meta valida la cadena de certificados.
  • Verify token incorrecto — handshake falla.
  • Procesar lógica antes de devolver 200 — timeout, Meta retreats.
  • No validar firma — riesgo de requests falsos.
  • No manejar duplicados — procesas el mismo evento dos veces.

La alternativa sin código: Aurora Inbox

Para 9 de cada 10 PYMEs, configurar webhooks raw es over-engineering. Aurora Inbox absorbe toda la complejidad:

  • Webhook configurado y mantenido por Aurora Inbox.
  • Procesamiento de mensajes entrantes con agente de IA listo.
  • Status updates trackeados en el dashboard.
  • Plantillas administradas en UI sin tocar API.
  • Calidad de número monitoreada con alertas tempranas.

Si necesitas extensibilidad, Aurora Inbox expone su propia API REST donde puedes suscribirte a eventos de aplicación más útiles que los raw de Meta:

  • conversation.created
  • conversation.assigned
  • ai_agent.escalated
  • lead.qualified
  • deal.stage_changed

Empieza tu prueba gratuita y conecta WhatsApp sin tocar webhooks raw.

Tabla comparativa

Appearance Webhook raw Cloud API Aurora Inbox
Implementation time 1-3 semanas 10 minutes
Mantenimiento ongoing 5-15 horas/mes 0
HTTPS / SSL A tu cargo Manejado
Validación de firma A tu cargo Manejado
Retries / idempotencia A tu cargo Manejado
Procesamiento del payload A tu cargo Hecho
Webhooks de aplicación DIY Disponibles

Por qué Aurora Inbox

Aurora Inbox absorbe la complejidad de webhooks de WhatsApp Business y expone webhooks de aplicación de mayor nivel para tus integraciones. Combina BSP nivel Meta + agente LLM + RAG + multicanal + REST API completa para extensibilidad.

Empieza tu prueba gratuita y deja la complejidad de webhooks raw atrás.

Frequently Asked Questions

¿Necesito un servidor para usar webhooks de WhatsApp?

Para Cloud API directa, sí. Para una plataforma como Aurora Inbox, no — la plataforma maneja el webhook.

¿Cuánto tarda configurar un webhook raw?

1-3 semanas para una implementación productiva con seguridad y retries. Aurora Inbox: 10 minutos.

¿Qué eventos manda Meta por webhook?

messages, statuses, message_template_status_update, business_capability_update, phone_number_quality_update.

¿Necesito HTTPS válido para webhooks?

Sí. Meta rechaza HTTP y certificados SSL inválidos.

¿Cómo evito procesar mensajes duplicados?

Cada mensaje tiene un wamid único. Guarda los IDs procesados y rechaza duplicados.

¿Puedo tener múltiples webhooks para el mismo número?

No directamente en Cloud API. La forma estándar es tener un único webhook que reenvía a múltiples destinos internos.

Create your AI chatbot

Aurora Inbox centralizes all your company's conversations and responds to your customers instantly

Active Aurora

Most recent posts

Create your AI chatbot

With Aurora IA Advisor, you'll never have to worry about unanswered messages again. Offer your customers a personalized and fluid interaction, while you can dedicate your time to continue growing your business.

Active Aurora