# Recibir respuestas y estados de WhatsApp por webhook

URL: https://wa.genuka.com/es/docs/guides/receive-messages-webhooks
Language: Spanish

> 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?

1. ### 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.

2. ### Regístrala

   En el panel, en **Webhooks**, o por la API:

   ```bash title="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.

3. ### 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.

4. ### 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.

```json title="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:

| `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](https://wa.genuka.com/es/docs/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages)):

```json title="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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/interactive)).
* `type: "button"` → `data.button.payload`: un botón de respuesta rápida en una plantilla
  ([documentación de Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/button)).
* `data.context.id`, cuando está presente, es el `wamid` del mensaje al que responde el cliente.

### ¿Cómo leo un estado de entrega?

```json title="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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)).

### ¿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:

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.

> [!NOTE]
> **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:

```ts title="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:

**Next.js**

```ts title="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 });
}
```

**Express**

```ts title="server.ts"
// Ejecútalo con tsx (`npx tsx server.ts`), que resuelve ./verify-signature.js al archivo .ts.
import express from "express";
import { verifySignature } from "./verify-signature.js";

const app = express();

// Declarado ANTES de app.use(express.json()): un parser global consumiría el cuerpo,
// y la firma nunca coincidiría.
app.post("/webhooks/genuka", express.raw({ type: "application/json" }), async (req, res) => {
  const raw = req.body.toString("utf8");
  const signature = req.get("X-Genuka-Signature") ?? null;
  if (!verifySignature(raw, signature, process.env.GENUKA_WEBHOOK_SECRET!)) {
    return res.status(401).send("invalid signature");
  }
  // Un evento de prueba se firma como uno real: no debe escribir nada en tu base de datos.
  if (req.get("X-Genuka-Test") === "true") return res.sendStatus(204);

  const event = JSON.parse(raw);
  const fresh = await saveEventOnce(event); // INSERT … ON CONFLICT (id) DO NOTHING
  res.sendStatus(204); // responder primero
  if (fresh) await queue.add("genuka-event", event); // procesar después, fuera de la solicitud
});

app.use(express.json()); // el resto de tu API
```

**Python (Flask)**

```python title="app.py"
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["GENUKA_WEBHOOK_SECRET"].encode()  # el secreto completo, incluido el prefijo whsec_
TOLERANCE_SECONDS = 300


def verify_signature(raw, header):
    if not header:
        return False
    timestamp, signatures = None, []
    for part in header.split(","):
        key, _, value = part.partition("=")
        key, value = key.strip(), value.strip()
        # isascii(): isdigit() por sí solo acepta "²", con el que int() lanza una excepción.
        if key == "t" and value.isascii() and value.isdigit():
            timestamp = int(value)
        elif key == "v1" and value:
            signatures.append(value)
    if timestamp is None or not signatures:
        return False
    # El timestamp forma parte del HMAC: fuera de la ventana, una solicitud capturada no sirve de nada.
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(SECRET, f"{timestamp}.".encode() + raw, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(s.encode(), expected.encode()) for s in signatures)


@app.post("/webhooks/genuka")
def genuka_webhook():
    raw = request.get_data()  # los bytes recibidos, antes de cualquier parseo
    if not verify_signature(raw, request.headers.get("X-Genuka-Signature")):
        abort(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 "", 204

    event = json.loads(raw)
    if save_event_once(event):  # INSERT … ON CONFLICT (id) DO NOTHING
        enqueue(event)  # Celery, RQ…: el procesamiento no retiene la respuesta
    return "", 204
```

**@genuka/whatsapp**

```ts title="app/api/webhooks/genuka/route.ts"
import { verifySignature } from "@genuka/whatsapp/webhooks";

export async function POST(request: Request) {
  const raw = await request.text();
  const ok = await verifySignature(
    process.env.GENUKA_WEBHOOK_SECRET!,
    raw,
    request.headers.get("x-genuka-signature"),
  );
  if (!ok) return new Response("invalid signature", { status: 401 });

  // … a partir de aquí, igual que en la pestaña Next.js
  return new Response(null, { status: 204 });
}
```

El `verifySignature` de la [biblioteca](https://wa.genuka.com/es/docs/library) es asíncrono (WebCrypto, por lo que también funciona en
un runtime edge) y requiere `@genuka/whatsapp` 0.1.1 o posterior.

## ¿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.

```sql title="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
);
```

```ts title="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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)).
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:

```bash title="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](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages)).
Reutiliza el `connection_id` del evento, antepón un `+` a `data.from` y cita el mensaje con
`replyTo`:

```json title="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](https://wa.genuka.com/es/docs/guides/order-notifications).

## 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

* [Meta — Messages webhook reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages)
* [Meta — Interactive message replies](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/interactive)
* [Meta — Button message replies](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/button)
* [Meta — Status messages webhook](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)
* [Meta — Send messages (customer service window)](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages)
