# Firma y verificación

> Cómo comprobar que una entrega de webhook viene de watsi verificando el encabezado X-Watsi-Signature (sha256=) en Node.js, Python, Ruby, Go y PHP.

Source: https://docs.watsi.ai/webhooks/signing

Cuando tu endpoint tiene un secreto de firma, cada entrega trae:

```http
X-Watsi-Signature: sha256=6b1f0c4e9d2a7b3c…
```

El valor es el prefijo `sha256=` seguido del **HMAC-SHA256 del cuerpo exacto** de la solicitud, con tu secreto como llave, en hexadecimal minúsculo. Para verificarlo calculas lo mismo de tu lado y comparas.

## El algoritmo

1. Lee el cuerpo **sin procesar**, los bytes tal como llegaron. No lo parsees y lo vuelvas a serializar: basta un espacio o un orden de claves distinto para que la firma no coincida.
2. Lee `X-Watsi-Signature`. Si falta o no empieza con `sha256=`, rechaza.
3. Calcula `HMAC-SHA256(secreto, cuerpo)` en hexadecimal.
4. Compara lo que viene después de `sha256=` con tu cálculo usando una comparación de **tiempo constante**.
5. Si no coinciden, responde `401` y descarta la entrega.

## Código

Cada ejemplo es una función que recibe el cuerpo sin procesar, el valor del encabezado y tu secreto, y devuelve `true` sólo si la firma es válida.

```javascript Node.js
import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyWatsiSignature(rawBody, header, secret) {
  if (typeof header !== 'string' || !header.startsWith('sha256=')) return false
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex')
  const received = header.slice('sha256='.length)
  if (received.length !== expected.length) return false
  return timingSafeEqual(Buffer.from(received), Buffer.from(expected))
}
```

```python Python
import hashlib
import hmac

def verify_watsi_signature(raw_body: bytes, header: str | None, secret: str) -> bool:
    if not header or not header.startswith("sha256="):
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(header[len("sha256="):], expected)
```

```ruby Ruby
require "openssl"

def verify_watsi_signature(raw_body, header, secret)
  return false unless header.is_a?(String) && header.start_with?("sha256=")
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, raw_body)
  OpenSSL.secure_compare(header.delete_prefix("sha256="), expected)
end
```

```go Go
package watsi

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strings"
)

func VerifyWatsiSignature(rawBody []byte, header, secret string) bool {
	const prefix = "sha256="
	if !strings.HasPrefix(header, prefix) {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(rawBody)
	expected := hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(strings.TrimPrefix(header, prefix)), []byte(expected))
}
```

```php PHP
<?php

function verify_watsi_signature(string $rawBody, ?string $header, string $secret): bool
{
    if ($header === null || !str_starts_with($header, 'sha256=')) {
        return false;
    }
    $expected = hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, substr($header, strlen('sha256=')));
}
```

## Obtener el cuerpo sin procesar

La mayoría de los frameworks parsean el JSON antes de que lo veas. Pide los bytes originales:

- **Express**: `app.post('/webhooks/watsi', express.raw({ type: 'application/json' }), handler)` y usa `req.body` (un `Buffer`).
- **Next.js (App Router)**: `const raw = await request.text()` antes de cualquier `request.json()`.
- **Flask**: `request.get_data()`.
- **Django**: `request.body`.
- **Rails**: `request.raw_post`.
- **Go `net/http`**: `io.ReadAll(r.Body)`.
- **PHP**: `file_get_contents('php://input')`.

Después de verificar, parsea esos mismos bytes como JSON.

## El secreto

- Pide el secreto al registrar tu endpoint; watsi te lo comparte por un canal seguro. Guárdalo en tu gestor de secretos, nunca en el código.
- Si tus entregas llegan **sin** `X-Watsi-Signature`, tu endpoint no tiene secreto todavía: pídelo a [support@watsi.ai](mailto:support@watsi.ai) antes de pasar a producción.
- Para rotarlo, pide uno nuevo. Mientras haces el cambio, acepta la firma calculada con cualquiera de los dos secretos.

## Errores comunes

- **Comparar el hexadecimal con el encabezado entero.** El encabezado empieza con `sha256=`; quítalo antes de comparar, o ninguna entrega real va a pasar.
- **Firmar el JSON re-serializado.** Firma los bytes que llegaron.
- **Comparar con `==`.** Usa la comparación de tiempo constante de tu lenguaje.
