Webhooks
Recibe mensajes entrantes, confirmaciones de entrega y cambios de estado.
Registras una URL y Genuka WA te entrega ahí cada evento como un POST firmado.
Registrar un endpoint
En el portal, en Webhooks: ingresa la URL (HTTPS obligatorio) y marca los eventos que quieres
recibir. El secreto de firma (whsec_…) se muestra una sola vez, al crearlo.
Un endpoint puede cubrir todos los números de tu cuenta (general), una empresa conectada o un solo número de teléfono; y una empresa puede excluirse de un endpoint general.
Eventos disponibles
| Evento | Contenido |
|---|---|
messages | Mensajes entrantes y estados de los mensajes que enviaste |
message_template_status_update | Una plantilla fue aprobada, rechazada o pausada |
account_update | Cambio en la cuenta: verificación, restricción, suspensión |
phone_number_quality_update | Cambió la calidad o el nivel de envío de un número |
connection.connected | Se acaba de conectar un número mediante tu enlace, con tu ref (consulta Conectar un número) |
call.connect · call.status_changed · call.terminated | Llamadas de WhatsApp (plan Growth o superior): entra o empieza una llamada (con el SDP en data.session), cambia de estado, termina (consulta Conectar un agente de voz) |
call.permission_replied | Un cliente respondió a una solicitud de permiso de llamada. También llega en messages, ya que es un mensaje. |
La plataforma no tiene bandeja de entrada: los webhooks son la forma de leer las respuestas.
El payload
Cada entrega es un POST que lleva un solo evento. data es el valor bruto de Meta, sin modificar,
salvo en los eventos que emite la propia plataforma (connection.connected); los campos que lo rodean te indican a qué empresa y a qué número pertenece.
{
"id": "dlv_2f8c1a...",
"type": "message_status",
"field": "messages",
"created_at": "2026-08-04T09:31:07.412Z",
"partner_id": "cl9x...",
"company_id": "cm31...",
"connection_id": "cn77...",
"waba_id": "102290129340398",
"phone_number_id": "106540352242922",
"data": {
"id": "wamid.HBgLMjM3...",
"status": "delivered",
"timestamp": "1785836801",
"recipient_id": "237699000000"
}
}Encabezados
| Encabezado | Contenido |
|---|---|
X-Genuka-Signature | La firma (ver más abajo) |
X-Genuka-Event | Tipo de evento, por ejemplo message_status |
X-Genuka-Event-Field | El campo de webhook de Meta subyacente, o el nombre del evento cuando no proviene de Meta |
X-Genuka-Delivery | Id de la entrega, idéntico entre reintentos: úsalo para eliminar duplicados |
X-Genuka-Webhook-Id | El endpoint al que se dirigió |
X-Genuka-Attempt | Número de intento, a partir de 1 |
Verificar la firma
El encabezado es X-Genuka-Signature, con la forma t=1785836801,v1=5f3c…, donde v1 es el
HMAC-SHA256 en hexadecimal de `${t}.${rawBody}` con tu secreto como clave.
La marca de tiempo está incluida en el MAC: eso es lo que impide reenviar una solicitud
capturada. Un receptor rechaza cualquier t fuera de su ventana de tolerancia (300 segundos por
defecto), y t no se puede modificar sin invalidar v1.
Firma el cuerpo bruto, exactamente como se recibió. Un JSON.parse seguido de un
JSON.stringify cambia el orden de las claves y los espacios: la firma nunca coincidirá.
import { verifySignature } from "@genuka/whatsapp/webhooks";
export async function POST(request: Request) {
const raw = await request.text();
const signature = request.headers.get("x-genuka-signature");
if (!(await verifySignature(process.env.WEBHOOK_SECRET!, raw, signature))) {
return new Response("invalid signature", { status: 401 });
}
// Procesa de forma asíncrona y responde de inmediato.
void handle(JSON.parse(raw));
return new Response("ok");
}Versión mínima: @genuka/whatsapp 0.1.1
verifySignature reconoce ambos esquemas y aplica el algoritmo correspondiente: el formato con
marca de tiempo de Genuka WA (t=…,v1=…) y el de Meta (X-Hub-Signature-256), este último solo
útil si también recibes webhooks de Meta directamente. En la 0.1.0 solo se manejaba el formato de
Meta: verificar un webhook de Genuka WA fallaba siempre.
Si no usas la biblioteca, el algoritmo cabe en unas pocas líneas:
import crypto from "node:crypto";
const TOLERANCE_SECONDS = 300;
export function verify(rawBody: string, header: string, secret: string): boolean {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const timestamp = Number(parts.t);
// Rechaza todo lo que esté fuera de la ventana: esto es lo que hace que una
// solicitud capturada no sirva para reenviarla más tarde.
if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(parts.v1, "utf8"),
Buffer.from(expected, "utf8"),
);
}Rota el secreto si sospechas que se expuso
La rotación surte efecto de inmediato: el secreto anterior deja de verificar en cuanto lo rotas, así que actualiza tu receptor en ese mismo momento.
Tres reglas de procesamiento
Responde 200 de inmediato
Haz el procesamiento en segundo plano. Un endpoint lento provoca reenvíos, que amplifican la carga justo en el peor momento.
Los eventos pueden duplicarse. El mismo mensaje puede entregársete dos veces. Haz que tu
procesamiento sea idempotente usando el id del mensaje (wamid) o X-Genuka-Delivery.
El orden no está garantizado. Una confirmación de lectura puede llegar antes que la confirmación
de entrega del mismo mensaje. Nunca hagas retroceder un estado: el orden lógico es sent →
delivered → read, y failed es terminal.
Estados de un mensaje enviado
| Estado | Significado |
|---|---|
sent | Aceptado por los servidores de WhatsApp |
delivered | Llegó al dispositivo del destinatario |
read | Leído; solo si el usuario activó las confirmaciones de lectura |
failed | Falló, con el código de error de Meta |
deleted | Mensaje eliminado |
Reintentos y fallos
Una entrega se considera exitosa con cualquier 2xx. Cualquier otra cosa, incluido un tiempo de
espera superior a 10 segundos, se reintenta 5 veces con un backoff creciente (1 min, 5 min, 30 min,
2 h, 6 h) y luego se marca como fallida.
Registro y reenvío
El portal conserva el historial de entregas: payload, estado HTTP, número de intentos y la respuesta de tu servidor. Si algo falló de tu lado, puedes reenviar un evento cuando tu endpoint vuelva a estar disponible.
Una clave API no interviene en la recepción de webhooks: lo único que hay que verificar del lado receptor es la firma. Nunca confíes en el contenido de un evento sin firmar.