Genuka WA docs

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:

POST /api/v1/webhooks
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.

POST https://api.example.com/webhooks/genuka
{
  "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:

typeQué esdata
inbound_messageUn mensaje del clienteEl objeto de mensaje de Meta
message_statussent, delivered, read o failed para un mensaje que enviasteEl objeto de estado de Meta
template_statusUna plantilla fue aprobada, rechazada o pausadaEl valor de cambio de Meta
account_updateUn cambio en la cuenta de WhatsApp BusinessEl valor de cambio de Meta
phone_qualityCambió la calidad o el nivel de un númeroEl 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):

data — el cliente tocó un botón de respuesta (mensaje interactivo)
{
  "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.id o data.interactive.list_reply.id, el id que 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 el wamid del mensaje al que responde el cliente.

¿Cómo leo un estado de entrega?

data — message_status en failed
{
  "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?

EncabezadoContenido
X-Genuka-Signaturet=<timestamp>,v1=<hex HMAC>
X-Genuka-EventEl type del evento
X-Genuka-Event-FieldEl campo de webhook de Meta subyacente
X-Genuka-DeliveryEl id de la entrega, igual al id del cuerpo, idéntico en todos los intentos
X-Genuka-Webhook-IdEl endpoint destinatario
X-Genuka-AttemptEl número de intento, a partir de 1
X-Genuka-Testtrue en un evento de prueba; ausente en los demás casos

¿Cómo verifico la firma HMAC?

El algoritmo, exactamente como firma Genuka WA:

  1. Lee el cuerpo sin procesar, antes de cualquier JSON.parse.
  2. De X-Genuka-Signature, lee t (segundos Unix) y cada v1 (puede haber varios).
  3. Rechaza si t se aleja más de 300 segundos de tu reloj.
  4. Calcula el HMAC-SHA256 en hexadecimal de la cadena t + . + cuerpo sin procesar, con el secreto completo como clave, incluido el prefijo whsec_.
  5. Acepta si uno de los valores v1 es 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:

verify-signature.ts
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:

app/api/webhooks/genuka/route.ts
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:

  1. verificar la firma;
  2. guardar el evento, sin duplicados gracias a su id — un insert, unos pocos milisegundos;
  3. responder 204;
  4. 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.

schema.sql
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
);
save-event-once.ts
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 propio id. En ese caso, elimina también los duplicados según la clave de negocio: data.id (el wamid) para un mensaje entrante, el par data.id + data.status para un estado.
  • Los eventos de prueba tienen un id que empieza por test_, el encabezado X-Genuka-Test: true y ningún encabezado X-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:

IntentoCuándo
1En cuanto llega el evento
2Al menos 1 minuto después de que falló el anterior
3Al menos 5 minutos después
4Al menos 30 minutos después
5Al menos 2 horas después
6Al 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:

Listar las entregas fallidas y luego reproducir una
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:

POST /api/v1/messages
{
  "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

En esta página