Genuka WA docs

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

EventoContenido
messagesMensajes entrantes y estados de los mensajes que enviaste
message_template_status_updateUna plantilla fue aprobada, rechazada o pausada
account_updateCambio en la cuenta: verificación, restricción, suspensión
phone_number_quality_updateCambió la calidad o el nivel de envío de un número
connection.connectedSe acaba de conectar un número mediante tu enlace, con tu ref (consulta Conectar un número)
call.connect · call.status_changed · call.terminatedLlamadas 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_repliedUn 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.

POST https://your-app.com/webhooks/whatsapp
{
  "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

EncabezadoContenido
X-Genuka-SignatureLa firma (ver más abajo)
X-Genuka-EventTipo de evento, por ejemplo message_status
X-Genuka-Event-FieldEl campo de webhook de Meta subyacente, o el nombre del evento cuando no proviene de Meta
X-Genuka-DeliveryId de la entrega, idéntico entre reintentos: úsalo para eliminar duplicados
X-Genuka-Webhook-IdEl endpoint al que se dirigió
X-Genuka-AttemptNú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:

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

EstadoSignificado
sentAceptado por los servidores de WhatsApp
deliveredLlegó al dispositivo del destinatario
readLeído; solo si el usuario activó las confirmaciones de lectura
failedFalló, con el código de error de Meta
deletedMensaje 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.

En esta página