Webhooks

Endpoints de webhook entrantes para canales Meta: Facebook Messenger, Instagram DM y WhatsApp.

Datos rápidos#

Los webhooks se reciben en helpstack.eu; usted registra esa URL de callback en el panel de Meta App. El token de verificación y el secreto de la aplicación son configurados por HelpStack (consulte las variables de entorno mencionadas a continuación).

Cómo funciona el handshake (todos los proveedores)#

Meta verifica un webhook enviando un GET con tres parámetros de consulta. HelpStack devuelve el challenge solo si el token de verificación coincide.

GET /api/webhooks/facebook
  ?hub.mode=subscribe
  &hub.verify_token=TOKEN
  &hub.challenge=CHALLENGE

• Si TOKEN coincide con el token de verificación configurado → responder 200 con el valor raw de CHALLENGE.
• De lo contrario → responder 403.

Cómo funciona la verificación de firma (todos los proveedores)#

Cada POST lleva un encabezado x-hub-signature-256. La firma se calcula sobre el cuerpo raw de la solicitud usando HMAC-SHA256 con clave FACEBOOK_APP_SECRET, precedida por sha256=.

x-hub-signature-256: sha256=<hex HMAC-SHA256(rawBody, FACEBOOK_APP_SECRET)>

Ejemplo en Node (cómo calcular/verificar):

import crypto from 'node:crypto';

function verifySignature(rawBody, headerValue, appSecret) {
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', appSecret).update(rawBody).digest('hex');
  return headerValue === expected;
}

Atención — use el cuerpo raw. La firma se calcula sobre los bytes exactos enviados por Meta. HelpStack lee el cuerpo como texto raw antes de parsear el JSON. Si construye su propio verificador, no vuelva a serializar el objeto JSON parseado (el orden de claves/espacios en blanco diferirá y la firma no coincidirá). Capture el string del cuerpo raw y calcule el HMAC sobre ese.

Facebook / Messenger#

Forma del payload entrante. El cuerpo contiene un array entry[]. Cada entrada tiene:

• entry[].messaging[] — formato Messenger heredado, o
• entry[].changes[] — formato más reciente.

Coincidencia de canal y procesamiento. El manejador hace coincidir un canal por facebookPageId / credentials.pageId, luego:

1. Crea o actualiza una conversación identificada por el PSID del remitente.
2. Almacena el mensaje entrante.
3. Obtiene el perfil del remitente y descarga adjuntos al almacenamiento.
4. Emite un evento en tiempo real al panel de control.

Instagram#

Hace coincidir canales gestionados por OAuth por id de cuenta de Instagram. El handshake y la verificación de firma funcionan igual que en Facebook.

WhatsApp#

Forma del payload entrante. El cuerpo contiene entry[].changes[].value con messages[] y contacts[]. El manejador hace coincidir un canal por credentials.phoneNumberId e identifica la conversación por el número de teléfono del remitente.

Variables de entorno#

Registrar en el panel de Meta App#

Para Messenger (el mismo patrón aplica a Instagram y WhatsApp con sus respectivos endpoints):

1. En el panel de Meta App, abra el producto (Messenger / Instagram / WhatsApp) → Webhooks.
2. URL de callback: https://helpstack.eu/api/webhooks/facebook (Instagram: .../api/webhooks/instagram, WhatsApp: .../api/webhooks/whatsapp.)
3. Token de verificación: el valor que configuró en FACEBOOK_VERIFY_TOKEN (o el token específico del proveedor).
4. Haga clic en Verify and Save — Meta envía el handshake GET; tiene éxito cuando el token coincide.
5. Suscribirse a campos: suscríbase a los campos messages / messaging para que los eventos de mensajes se entreguen.
6. Asegúrese de que el App Secret de su aplicación coincida con FACEBOOK_APP_SECRET para que la verificación de firma pase en POST.

Después de guardar, envíe un mensaje de prueba a la página/cuenta — debería aparecer como una nueva conversación en el panel de control.

Relacionado#

• Referencia de la API
• Canal de email
• Guía de canales
• Glosario