Recibir respuestas y estados de WhatsApp por webhook
Recibe respuestas de WhatsApp y estados de entrega en tu servidor: registra un webhook, verifica la firma HMAC, elimina duplicados, gestiona los reintentos y la reproducción.
Para recibir las respuestas de WhatsApp y los estados de entrega, registra una URL HTTPS en Genuka WA: cada evento
llega allí como un POST firmado. Tu endpoint verifica la firma HMAC-SHA256 del encabezado
X-Genuka-Signature contra el cuerpo sin procesar, guarda el evento una sola vez usando su id, responde
2xx en menos de 10 segundos y luego lo procesa en segundo plano.
Última actualización: 8 de octubre de 2026
¿Cómo registro un endpoint de webhook?
Expón una URL HTTPS pública
Genuka WA rechaza las URLs http://, las URLs que llevan usuario y contraseña, y las URLs que apuntan a una
dirección privada o local. Para desarrollar en tu máquina, usa un túnel HTTPS. Las redirecciones no
se siguen: una respuesta 3xx cuenta como fallo, así que registra la URL final exacta.
Regístrala
En el panel, en Webhooks, o por la API:
curl -X POST https://wa.genuka.com/api/v1/webhooks \
-H "Authorization: Bearer $GENUKA_WA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.example.com/webhooks/genuka",
"connectionId": "con_1",
"events": ["message.received", "message.sent", "message.delivered", "message.read",
"message.failed", "template.status_changed"]
}'Sin connectionId ni companyId, el endpoint cubre todos los números que tu clave puede alcanzar. Un
events vacío o ausente significa "todos los eventos". template.status_changed trae el veredicto de Meta sobre
tus plantillas (el evento template_status): sin él, un endpoint suscrito solo a los mensajes
nunca lo recibe.
Copia el secreto
La respuesta 201 contiene secret (whsec_…). Solo se devuelve en la creación y en la rotación
(PATCH /api/v1/webhooks/{id} con "rotateSecret": true): guárdalo en tu entorno, por
ejemplo como GENUKA_WEBHOOK_SECRET. Una rotación surte efecto de inmediato.
Pruébalo
POST /api/v1/webhooks/{id}/test envía a tu URL un ejemplo de cada familia de eventos y devuelve el
estado HTTP que obtuvo para cada uno. Los ejemplos están firmados con tu secreto, como una entrega real: así
pruebas tu verificación de la firma antes del primer mensaje real.
¿Cómo es un evento?
Cada entrega es un POST JSON que contiene un evento. Los campos alrededor de data te indican a qué
negocio y a qué número pertenece; connection_id es el que debes reutilizar cuando respondas.
{
"id": "cmg7v2k0x0001…",
"type": "inbound_message",
"field": "messages",
"created_at": "2026-10-08T09:31:07.412Z",
"partner_id": "cl9x…",
"company_id": "cm31…",
"connection_id": "cn77…",
"waba_id": "102290129340398",
"phone_number_id": "106540352242922",
"data": {
"from": "237699001122",
"id": "wamid.HBgLMjM3…",
"timestamp": "1791451865",
"type": "text",
"text": { "body": "Mañana no estaré en casa" }
}
}Para los cinco tipos históricos, data es el objeto sin procesar que envió Meta, intacto:
type | Qué es | data |
|---|---|---|
inbound_message | Un mensaje del cliente | El objeto de mensaje de Meta |
message_status | sent, delivered, read o failed para un mensaje que enviaste | El objeto de estado de Meta |
template_status | Una plantilla fue aprobada, rechazada o pausada | El valor de cambio de Meta |
account_update | Un cambio en la cuenta de WhatsApp Business | El valor de cambio de Meta |
phone_quality | Cambió la calidad o el nivel de un número | El valor de cambio de Meta |
Los eventos más recientes llevan un nombre de Genuka (user_preference.stopped, template.quality_changed,
unknown.received…) y un data normalizado. Ramifica siempre según type, e ignora sin generar un error lo que no
gestionas: pueden aparecer tipos nuevos. Consulta también la
referencia de Webhooks.
¿Cómo leo la respuesta de un cliente?
Lo que contiene un inbound_message depende de data.type
(documentación de Meta, incoming messages):
{
"context": { "from": "237690000000", "id": "wamid.of_the_message_you_sent…" },
"from": "237699001122",
"id": "wamid.HBgL…",
"timestamp": "1791451865",
"type": "interactive",
"interactive": { "type": "button_reply", "button_reply": { "id": "yes", "title": "Confirmar" } }
}type: "text"→data.text.body.type: "interactive"→data.interactive.button_reply.idodata.interactive.list_reply.id, elidque le diste al botón o a la fila (documentación de Meta).type: "button"→data.button.payload: un botón de respuesta rápida en una plantilla (documentación de Meta).data.context.id, cuando está presente, es elwamiddel mensaje al que responde el cliente.
¿Cómo leo un estado de entrega?
{
"id": "wamid.HBgLMjM3…",
"status": "failed",
"timestamp": "1791451901",
"recipient_id": "237699001122",
"errors": [{ "code": 131026, "title": "…" }]
}data.id es el messageId devuelto por POST /api/v1/messages. errors solo aparece en caso de
fallo (documentación de Meta, statuses).
¿Qué encabezados acompañan cada entrega?
| Encabezado | Contenido |
|---|---|
X-Genuka-Signature | t=<timestamp>,v1=<hex HMAC> |
X-Genuka-Event | El type del evento |
X-Genuka-Event-Field | El campo de webhook de Meta subyacente |
X-Genuka-Delivery | El id de la entrega, igual al id del cuerpo, idéntico en todos los intentos |
X-Genuka-Webhook-Id | El endpoint destinatario |
X-Genuka-Attempt | El número de intento, a partir de 1 |
X-Genuka-Test | true en un evento de prueba; ausente en los demás casos |
¿Cómo verifico la firma HMAC?
El algoritmo, exactamente como firma Genuka WA:
- Lee el cuerpo sin procesar, antes de cualquier
JSON.parse. - De
X-Genuka-Signature, leet(segundos Unix) y cadav1(puede haber varios). - Rechaza si
tse aleja más de 300 segundos de tu reloj. - Calcula el HMAC-SHA256 en hexadecimal de la cadena
t+.+ cuerpo sin procesar, con el secreto completo como clave, incluido el prefijowhsec_. - Acepta si uno de los valores
v1es igual, comparando en tiempo constante.
Una reentrega tardía sigue pasando la ventana
Cada intento se firma al salir, con un t nuevo. Un reintento seis horas después, o una
reproducción manual, es por lo tanto aceptado por la tolerancia de 300 segundos; una solicitud capturada y reproducida por un
tercero no lo es, porque t no se puede modificar sin invalidar v1.
La función de verificación, sin dependencias:
import crypto from "node:crypto";
const TOLERANCE_SECONDS = 300;
export function verifySignature(rawBody: string, header: string | null, secret: string): boolean {
if (!header) return false;
let timestamp = Number.NaN;
const signatures: string[] = [];
for (const part of header.split(",")) {
const [key, value] = part.split("=", 2).map((s) => s.trim());
if (key === "t") timestamp = Number(value);
if (key === "v1" && value) signatures.push(value);
}
if (!Number.isFinite(timestamp) || signatures.length === 0) return false;
// El timestamp forma parte del HMAC: fuera de la ventana, una solicitud capturada no sirve de nada.
if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;
const expected = crypto
.createHmac("sha256", secret) // el secreto completo, incluido el prefijo whsec_
.update(`${timestamp}.${rawBody}`)
.digest("hex");
// timingSafeEqual lanza una excepción con dos buffers de longitudes en bytes distintas, y el encabezado lo escribe
// quien envía la solicitud: compara las longitudes en bytes, no las de las cadenas ("é" es un
// carácter pero dos bytes), o un encabezado falsificado convierte un 401 en un 500.
const expectedBytes = Buffer.from(expected);
return signatures.some((candidate) => {
const candidateBytes = Buffer.from(candidate);
return (
candidateBytes.length === expectedBytes.length &&
crypto.timingSafeEqual(candidateBytes, expectedBytes)
);
});
}Luego el endpoint, según tu framework:
import { after } from "next/server";
import { verifySignature } from "@/lib/verify-signature";
export async function POST(request: Request) {
const raw = await request.text(); // el cuerpo exactamente como se firmó
const signature = request.headers.get("x-genuka-signature");
if (!verifySignature(raw, signature, process.env.GENUKA_WEBHOOK_SECRET!)) {
return new Response("invalid signature", { status: 401 });
}
// Un evento de prueba se firma como uno real: no debe escribir nada en tu base de datos.
if (request.headers.get("x-genuka-test") === "true") return new Response(null, { status: 204 });
const event = JSON.parse(raw);
// Primero guardar (rápido, sin duplicados gracias a event.id), procesar después de la respuesta.
const fresh = await saveEventOnce(event);
if (fresh) after(() => processEvent(event));
return new Response(null, { status: 204 });
}¿Cómo respondo lo bastante rápido para evitar reentregas?
Una entrega se considera exitosa con cualquier 2xx. Todo lo demás falla y se reintentará: un estado 4xx o 5xx,
una redirección, o una respuesta que tarda más de 10 segundos.
La secuencia que resiste bajo carga:
- verificar la firma;
- guardar el evento, sin duplicados gracias a su
id— un insert, unos pocos milisegundos; - responder
204; - procesar después, en
after(), una cola de trabajos o un worker.
Responde 5xx solo si falló el propio guardado: es el único caso en que necesitas que Genuka WA lo intente
de nuevo. Un procesamiento que falla después de la respuesta se vuelve a ejecutar desde tu tabla, no desde el webhook.
¿Cómo elimino los eventos duplicados?
El id del cuerpo — igual al encabezado X-Genuka-Delivery — es idéntico en todos los intentos y en una
reproducción manual. Es tu clave de idempotencia.
create table genuka_events (
id text primary key, -- el id del cuerpo, estable entre intentos
type text not null,
payload jsonb not null,
received_at timestamptz not null default now(),
processed_at timestamptz -- null hasta que el procesamiento tenga éxito
);export async function saveEventOnce(event: { id: string; type: string }): Promise<boolean> {
const result = await db.query(
"insert into genuka_events (id, type, payload) values ($1, $2, $3) on conflict (id) do nothing",
[event.id, event.type, JSON.stringify(event)],
);
return result.rowCount === 1; // false: ya recibido, no hay nada que hacer
}Dos puntos más:
- Varios endpoints, varios
id. Si dos de tus endpoints cubren el mismo número, cada uno recibe su propia entrega, con su propioid. En ese caso, elimina también los duplicados según la clave de negocio:data.id(elwamid) para un mensaje entrante, el pardata.id+data.statuspara un estado. - Los eventos de prueba tienen un
idque empieza portest_, el encabezadoX-Genuka-Test: truey ningún encabezadoX-Genuka-Delivery. Fíltralos antes de escribir nada en tu base de datos, como hacen los ejemplos anteriores.
Por último, el orden no está garantizado: un read puede llegar antes que el delivered del mismo mensaje,
y delivered puede no llegar nunca. Cuando el cliente tiene el chat abierto en el momento en que llega el mensaje,
Meta lo considera entregado y leído a la vez y envía solo read
(documentación de Meta, statuses).
Así que trata read como si implicara delivered, y nunca hagas retroceder un estado — sent →
delivered → read, y failed es definitivo.
¿Qué pasa si mi servidor está caído?
Genuka WA hace hasta seis intentos en total:
| Intento | Cuándo |
|---|---|
| 1 | En cuanto llega el evento |
| 2 | Al menos 1 minuto después de que falló el anterior |
| 3 | Al menos 5 minutos después |
| 4 | Al menos 30 minutos después |
| 5 | Al menos 2 horas después |
| 6 | Al menos 6 horas después; luego la entrega se marca como failed |
Los reintentos salen de una cola que se vacía cada 10 minutos, así que un intento puede llegar hasta unos diez minutos después de su plazo mínimo, o más con mucha acumulación.
Cuando tu endpoint vuelva a funcionar, busca lo que falló y reprodúcelo:
curl "https://wa.genuka.com/api/v1/webhooks/wh_1/deliveries?status=failed" \
-H "Authorization: Bearer $GENUKA_WA_API_KEY"
curl -X POST https://wa.genuka.com/api/v1/webhooks/wh_1/deliveries/cmg7v2k0x0001/replay \
-H "Authorization: Bearer $GENUKA_WA_API_KEY"La reproducción responde 202 y empieza de nuevo con un presupuesto de intentos nuevo. Una entrega que sigue en pending
se rechaza (409 delivery_pending): ya está en la cola. El registro conserva el cuerpo exacto de cada
entrega; el tiempo de conservación depende de tu plan y se indica en meta.retentionDays. La
sección Webhooks del panel ofrece el mismo registro y el mismo botón de reenvío.
¿Cómo respondo a un mensaje que recibí?
Mientras el cliente te haya escrito en las últimas 24 horas, puedes responder con texto libre
(documentación de Meta).
Reutiliza el connection_id del evento, antepón un + a data.from y cita el mensaje con
replyTo:
{
"connectionId": "cn77…",
"to": "+237699001122",
"replyTo": "wamid.HBgLMjM3…",
"text": "¡Gracias, anotado!"
}Para mostrar las palomitas azules, llama a POST /api/v1/messages/{wamid}/read con { "connectionId": … } en
el cuerpo — con el wamid codificado para URL. Fuera de la ventana necesitas una plantilla: consulta
Notificaciones de pedidos.
Preguntas frecuentes
¿Por qué mi firma nunca coincide?
Casi siempre por una de estas cuatro causas: el cuerpo se parseó y se volvió a serializar antes de la verificación (un
express.json() global, por ejemplo); el secreto se copió sin su prefijo whsec_; el
reloj del servidor se desvía más de cinco minutos; o el secreto se rotó desde entonces.
¿Puedo recibir directamente los webhooks de Meta?
No. Los webhooks de la Cloud API llegan a Genuka WA, que te los retransmite firmados con tu secreto. Para los
cinco tipos históricos, data sigue siendo el objeto original de Meta: el código que ya lee el formato de Meta
se siente como en casa.
¿Necesito una clave API para recibir webhooks?
No. Lo único que hay que verificar del lado receptor es la firma. Nunca proceses un evento sin firmar.
¿Los estados llegan en orden?
No: read puede llegar antes que delivered, o incluso llegar solo. Ordena los estados por rango, trata read como si
implicara delivered, y nunca los hagas retroceder.
Fuentes
Enviar una campaña de WhatsApp por la API
Envía una campaña de WhatsApp por la API: plantilla de marketing, destinatarios, lanzamiento, cuotas del plan, límites de marketing de Meta y seguimiento de la entrega.
Coexistencia: API de WhatsApp y la app Business
Conserva la app WhatsApp Business en tu número mientras usas la API: requisitos (2.24.17+), pasos de conexión, qué se sincroniza y los límites.