# Webhooks

URL: https://wa.genuka.com/es/docs/webhooks
Language: Spanish

> 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](https://wa.genuka.com/es/docs/onboarding))                                                                                     |
| `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](https://wa.genuka.com/es/docs/guides/voice-agent)) |
| `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.

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

| 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`.

> [!WARNING]
> 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á.

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

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

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

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

> [!WARNING]
> **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.

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