Verificar firma HMAC

Tu URL de webhook es pública por necesidad — INGALCA Pay tiene que poder pegarle. Eso significa que cualquiera podría intentar mandarte requests falsos simulando pagos exitosos. La firma HMAC-SHA256 te permite verificar que cada webhook realmente viene de nosotros.

Verificá siempre

Si confiás en el body sin verificar la firma, un atacante puede mandarte falsos payment.confirmed y entregar tu producto sin pagar.

Cómo se calcula

La firma cubre el timestamp y el body juntos, unidos por un punto:

firma = "sha256=" + hmac_sha256(secret, timestamp + "." + body_json_exacto)

• secret — tu webhook secret (whsec_...). Lo configurás en Configuración → Webhooks → Rotar secret. Es distinto por entorno.
• timestamp — el valor del header X-Ingalca-Timestamp (unix timestamp, como string). Va firmado dentro del HMAC, así que un atacante no puede alterarlo para burlar el chequeo anti-replay.
• body_json_exacto — el cuerpo de la request byte por byte como llega. No lo parsees ni lo reformatees antes de firmar; usá el raw body.

Nota

El separador es un punto (.) literal entre el timestamp y el body: 1712000000.{"event":...}.

Cómo verificar

Node.js

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.INGALCA_WEBHOOK_SECRET;

// Importante: usar raw body, NO express.json() acá
app.post('/webhooks/ingalca', express.raw({ type: 'application/json' }), (req, res) => {
    const signature = req.headers['x-ingalca-signature'];
    const timestamp = req.headers['x-ingalca-timestamp'];

    // Firmá timestamp + "." + body. req.body es un Buffer (raw); actualizamos
    // el HMAC en dos pasos para no coercionar el Buffer a string.
    const hmac = crypto.createHmac('sha256', SECRET);
    hmac.update(timestamp + '.');
    hmac.update(req.body);
    const expected = 'sha256=' + hmac.digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
        return res.status(401).send('invalid signature');
    }

    const event = JSON.parse(req.body.toString());
    // ... procesar event ...

    res.sendStatus(200);
});

PHP / Laravel

Route::post('/webhooks/ingalca', function (Request $request) {
    $signature = $request->header('X-Ingalca-Signature');
    $timestamp = $request->header('X-Ingalca-Timestamp');
    $body      = $request->getContent(); // raw body

    $signed   = $timestamp . '.' . $body;
    $expected = 'sha256=' . hash_hmac('sha256', $signed, env('INGALCA_WEBHOOK_SECRET'));

    if (! hash_equals($expected, $signature)) {
        return response('invalid signature', 401);
    }

    $event = json_decode($body, true);
    // ... procesar event ...

    return response('', 200);
});

Python (Flask)

import hmac
import hashlib
import os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ['INGALCA_WEBHOOK_SECRET'].encode()

@app.post('/webhooks/ingalca')
def webhook():
    signature = request.headers.get('X-Ingalca-Signature', '')
    timestamp = request.headers.get('X-Ingalca-Timestamp', '')
    body      = request.get_data()  # raw bytes

    signed   = timestamp.encode() + b'.' + body
    expected = 'sha256=' + hmac.new(SECRET, signed, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401)

    event = request.get_json()
    # ... procesar event ...

    return '', 200

Qué NO hacer

• No uses == para comparar firmas. Es vulnerable a timing attacks. Usá crypto.timingSafeEqual (Node), hash_equals (PHP), hmac.compare_digest (Python).
• No re-serialices el body. Si convertís el JSON a objeto y lo volvés a stringify, vas a alterar espacios/orden y la firma no va a matchear.
• No expongas el secret en logs. Trátalo como una contraseña.

Rotar el secret

Si sospechás que tu secret se filtró, rotalo desde Configuración → Webhooks. El cambio es inmediato — los próximos webhooks van firmados con el secret nuevo. Asegurate de actualizar tu env var antes de rotar, sino vas a empezar a rechazar webhooks legítimos.

Replay attacks

El header X-Ingalca-Timestamp te permite rechazar webhooks demasiado viejos:

const timestamp = parseInt(req.headers['x-ingalca-timestamp'], 10);
const ageSeconds = Math.floor(Date.now() / 1000) - timestamp;

if (ageSeconds > 300) {
    return res.status(401).send('webhook too old');
}

5 minutos de tolerancia suele ser razonable. Más tiempo te deja vulnerable a replays; menos tiempo puede causar falsos negativos por desfase de reloj.