Cómo enviar eventos de WhatsApp a tu servidor con webhooks

Los webhooks salientes dejan que WACRM envíe un evento de WhatsApp a una URL que controlas, firmado para que puedas confirmar que de verdad vino de WACRM, en lugar de que tu servidor esté consultando la API para ver qué cambió. Esta guía cubre los dos lugares que administran los mismos endpoints de webhook — la pantalla Settings → Apps & Connectors → Webhooks de Workspace y la Core API directamente — y dice con claridad qué eventos, reintentos y límites existen hoy.

Qué necesitas antes de empezar

• Una cuenta de WACRM Workspace con al menos un proyecto, en el plan Advanced o superior (con acceso de propietario, para administrar webhooks desde Workspace).
• Un servidor que controles, capaz de recibir una solicitud POST por HTTPS y responder con un estado 2xx.
• Solo para los pasos de la API: curl (o cualquier cliente HTTP que pueda poner un encabezado), y una API key con los scopes wa_webhooks:read/wa_webhooks:write desde Developer / API & MCP.

Añade un endpoint de webhook en Workspace

1. Abre Settings → Apps & Connectors → Webhooks. Esta pantalla es solo para el propietario — un miembro del equipo sin acceso de propietario no verá ninguna forma de añadir o cambiar un endpoint aquí.
2. Haz clic en Add endpoint.
3. Escribe la Endpoint URL de tu servidor — debe empezar con https://, y se rechaza si resuelve a una dirección privada, loopback, link-local u otra dirección reservada (se vuelve a comprobar al momento de la entrega, así que un hostname al que le cambian el destino después de crearlo también queda atrapado).
4. Marca los Events to send que quieras: message.inbound (llegó un mensaje de WhatsApp) y/o message.status (cambió el estado de entrega de un mensaje). Son los únicos dos eventos disponibles hoy.
5. Haz clic en Create endpoint.

Un diálogo Your new webhook signing secret se abre de inmediato tras crearlo, mostrando el secreto exactamente una vez — cópialo ahora. WACRM nunca guarda ni registra una copia legible de él, y no puede volver a mostrar ese mismo secreto; si lo pierdes, rótalo por uno nuevo (ver abajo).

Verifica la firma en tu servidor

Cada entrega — un evento real, un reenvío o un envío de prueba — lleva un encabezado X-WACRM-Signature con la forma t=<marca de tiempo unix>,v1=<HMAC-SHA256 en hex de "<t>.<cuerpo crudo>", firmado con el secreto de tu endpoint>. Recalcula el mismo HMAC sobre el cuerpo exacto de la solicitud y compáralo con v1 antes de confiar en el payload; nunca confíes solo en el cuerpo. Es el mismo patrón de webhook firmado que usan la mayoría de proveedores de webhooks (ver las fuentes de HMAC y webhooks más abajo) — con marcadores de posición en vez de tu secreto real, nunca uno verdadero:

const crypto = require('crypto');

// header: el valor crudo de X-WACRM-Signature; rawBody: los bytes exactos que envió WACRM,
// no un JSON.parse(body) reserializado — las diferencias de espacios rompen el HMAC.
function isValidWebhookSignature(header, rawBody, endpointSecret) {
  const [tPart, v1Part] = header.split(',');
  const timestamp = tPart.split('=')[1];
  const expected = crypto
    .createHmac('sha256', endpointSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return v1Part === `v1=${expected}`;
}

Envía una prueba, revisa Deliveries y reenvía una que haya fallado

1. Desde la fila del endpoint, haz clic en Send test. Esto envía exactamente un evento webhook.test firmado por la misma ruta de entrega, la misma verificación SSRF y la misma firma que un evento real — útil para confirmar que tu servidor valida bien la firma antes de conectar tráfico real. Tiene un tope de 5 envíos de prueba por endpoint por minuto; un sexto dentro del mismo minuto se rechaza.
2. Haz clic en Deliveries para abrir la lista de todo lo enviado a este endpoint — evento, estado, estado HTTP, intentos y la hora del último intento, de más reciente a más antiguo. Las entregas se conservan 30 días y luego se eliminan.
3. Para una entrega marcada como Failed, haz clic en Redeliver. Esto reenvía exactamente el mismo payload como una entrega completamente nueva — la fila fallida original se conserva tal cual, así que sigues teniendo un registro de lo que pasó la primera vez.

Un endpoint apagado (Active desactivado) rechaza de plano tanto Send test como Redeliver — actívalo de nuevo primero.

Rota el secreto

Si tu secreto se filtra, o simplemente quieres uno nuevo, haz clic en Rotate secret en la fila del endpoint. Se abre el mismo diálogo de revelado único con el secreto nuevo — cópialo de inmediato, porque el secreto anterior deja de verificar entregas al instante, sin ninguna ventana de solapamiento para firmas en camino. Actualiza tu servidor con el secreto nuevo antes de rotarlo, o tu verificación empezará a fallar en el momento en que confirmes.

Haz lo mismo por la API

Todo lo de arriba también es accesible directamente, con alcance wa_webhooks:read/wa_webhooks:write — marca ambos en Restrict what this key can do (advanced) → WhatsApp CRM scopes al crear una key en Developer / API & MCP. Ninguno de los dos scopes se otorga por defecto a ninguna key, porque un endpoint recibe el contenido de mensajes real de tu proyecto.

curl -s -X POST https://api.wacrm.ai/v1/webhook-endpoints \
  -H "Authorization: Bearer sk_live_your_scoped_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhook", "events": ["message.inbound", "message.status"]}'

{
  "data": {
    "id": "7e9b9b7a-...-endpoint-uuid",
    "url": "https://your-server.com/webhook",
    "events": ["message.inbound", "message.status"],
    "active": true,
    "created_at": "2026-11-08T09:00:00+00:00",
    "secret": "whsec_your_one_time_secret"
  }
}

secret solo aparece en esta respuesta de creación y en una respuesta de rotate-secret — cualquier otra llamada, incluso volver a pedir el mismo endpoint, lo omite por completo. Un proyecto puede tener como máximo 20 endpoints; crear un 21.º responde 409 {"error": {"code": "endpoint_limit_reached"}}. PATCH toma el campo que estés cambiando entre url/events/active (se necesita al menos uno) y nunca devuelve un secret. Un reenvío o un envío de prueba contra un endpoint con active: false responde 409 {"error": {"code": "endpoint_inactive"}} antes de que corra nada más; un sexto envío de prueba en el mismo minuto responde 429 {"error": {"code": "rate_limited"}}.

Qué funciona hoy y qué no

¿Listo para probar esto en tu propio proyecto? Solicita acceso anticipado para obtener un Workspace, o consulta precios primero si todavía estás comparando planes. Para más guías como esta, explora la lista completa de guías.