# Verificar la firma

> Cómo confirmar que un webhook realmente vino de Messajo, con ejemplos en varios lenguajes.

## Por qué verificar

La URL de tu webhook es pública. Sin verificar la firma, cualquiera que descubra la URL puede enviar eventos falsos — un "mensaje recibido" inventado, un "pago" que nunca ocurrió. La firma prueba que el cuerpo vino de Messajo, con tu secreto, y que no se alteró en el camino. La hora dentro de ella impide que alguien grabe una entrega y la repita después.

## La cabecera

Cada entrega trae la cabecera `Messajo-Signature`:

```text
Messajo-Signature: t=1762697007,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

- `t` es la hora de la firma, en segundos Unix. Aparece una sola vez.
- `v1` es el HMAC-SHA256 en hexadecimal. Durante la [rotación del secreto](#rotar-el-secreto-sin-interrupciones) llegan **dos** `v1`, uno por secreto activo: basta con que uno coincida.
- Ignora los esquemas que no conoces (un `v2=` futuro, por ejemplo).

El secreto del destino empieza con `whsec_` y aparece **una sola vez**, al crear el destino (en el panel o en la respuesta de `POST /v1/destinations`). Después el panel muestra solo los últimos 4 caracteres. ¿Lo perdiste? Rota el secreto.

## Paso a paso

1. Lee el **cuerpo crudo** de la petición, exactamente los bytes que llegaron, **antes** de cualquier parseo de JSON.
2. Separa `t` y los `v1` de la cabecera.
3. Arma el mensaje `${t}.${cuerpo}` — la hora, un punto y el cuerpo crudo.
4. Calcula el HMAC-SHA256 de ese mensaje usando como clave el **secreto entero**, con el prefijo `whsec_`, en UTF-8. El resultado en hexadecimal en minúsculas.
5. Compara con cada `v1` en **tiempo constante** (`timingSafeEqual`, `hmac.compare_digest`, `hash_equals`). Comparar con `==` filtra información por el tiempo de respuesta.
6. Rechaza si `t` está a más de **5 minutos** de tu reloj, hacia atrás o hacia adelante.

Firma inválida → responde `400` y descarta el evento. Válida → responde `2xx` rápido y procesa después (mira [Eventos](/es/webhooks/events/#orden-y-duplicados)).

## Ejemplos

Los tres ejemplos no usan bibliotecas externas y se prueban en cada build contra el firmador de Messajo.

### Node.js

<Code code={nodeSnippet} lang="ts" title="verify.ts" />

### Python

<Code code={pythonSnippet} lang="python" title="verify.py" />

### PHP

<Code code={phpSnippet} lang="php" title="verify.php" />

Cómo obtener el cuerpo crudo en cada framework:

| Framework | Cuerpo crudo |
|---|---|
| Express | `app.post("/webhook", express.raw({ type: "application/json" }), …)` y `req.body.toString("utf8")` |
| Hono | `await c.req.text()` |
| FastAPI | `await request.body()` |
| Laravel | `$request->getContent()` |

Usa el cuerpo crudo en la verificación y solo después haz el `JSON.parse` / `json.loads` / `json_decode`.

## n8n

1. En el nodo **Webhook**, en **Options**, activa **Raw Body**.
2. Después, un nodo **Code** (JavaScript) con el código del ejemplo de Node.js, leyendo la cabecera `messajo-signature` y el cuerpo crudo del ítem recibido.
3. El nodo Code solo carga `crypto` si n8n lo permite: define `NODE_FUNCTION_ALLOW_BUILTIN=crypto` en el entorno de n8n y reinícialo.
4. Firma inválida → detén el flujo (nodo **Stop and Error** o un **IF**).

## Rotar el secreto sin interrupciones

1. En el panel, abre el destino y haz clic en **Rotar secreto**, o llama a `POST /v1/destinations/{id}/rotate-secret`. Messajo genera un secreto nuevo y lo muestra una sola vez.
2. Elige la **ventana de convivencia**: de 0 a 72 horas, **24 horas** por defecto (`keep_previous_hours` en la API). Durante la ventana los dos valen y cada entrega llega con dos `v1`, primero el del secreto nuevo, después el del viejo:

   ```text
   Messajo-Signature: t=1762697007,v1=<hmac con el nuevo>,v1=<hmac con el viejo>
   ```

3. Cambia el secreto en tu aplicación dentro de la ventana. Como basta con que un `v1` coincida, no hay momento en que se rechacen eventos. El fin de la ventana aparece en el destino (`previous_secret_expires_at` en la API).
4. Pasada la ventana, el secreto viejo deja de firmar y las entregas vuelven a tener un solo `v1`.

Con ventana `0` el viejo deja de firmar en el acto: úsala solo cuando el secreto se filtró. Rotar de nuevo dentro de la ventana descarta el más antiguo: valen solo el secreto actual y el que acaba de reemplazar.

## Errores comunes

- **JSON re-serializado.** El framework parseó el cuerpo y firmaste `JSON.stringify(req.body)`. Espacios, orden de claves y escape de acentos cambian y el HMAC no coincide. Usa el cuerpo crudo.
- **Reloj equivocado.** Un servidor sin NTP se sale de los 5 minutos y rechaza todo como viejo. Sincroniza el reloj.
- **Secreto con espacio.** Un espacio o salto de línea al final del secreto copiado (común en `.env`). Revisa el largo y quita los espacios.
- **Secreto sin el prefijo.** La clave del HMAC es el secreto entero, **con** `whsec_`.
- **Cuerpo decodificado con otro charset.** Lee los bytes como UTF-8; acentos y emojis importan.
