← Blog
10 min de lectura
|
Publicado
|
Actualizado

Verificación de firmas de webhooks con secretos personales

Defina un secreto personal y Chaingateway firma cada webhook con una cabecera X-Signature. Cómo funciona el HMAC, una comprobación en Node.js y qué no cubre.

Capítulos
C
Chaingateway Team
Expertos en blockchain

Revisado por Maurice Sobiera

Un secreto personal es una clave que usted define en su perfil de Chaingateway. Una vez creada, cada webhook saliente lleva una cabecera X-Signature: un HMAC-SHA256 del ID de la transacción, firmado con ese secreto y codificado en Base64. Su servidor recalcula el valor y lo compara, lo que demuestra que la petición procede de Chaingateway.

¿Por qué necesitan los webhooks una firma?

Un endpoint de webhook es una URL pública, y cualquiera que la conozca puede enviarle una petición. Sin una comprobación, una petición falsa de «pago recibido» podría liberar mercancía o abonar una cuenta. Un secreto compartido resuelve esto. Solo Chaingateway y su servidor conocen la clave, así que solo ellos pueden producir una firma coincidente. La construcción es HMAC, definida en la RFC 2104: una función hash combinada con una clave secreta.

¿Cómo se define un secreto personal?

Abra la configuración de su perfil en el panel, localice la tarjeta del secreto personal de webhooks y haga clic en «Set Personal Secret». Para reemplazar un secreto existente, haga clic en «Regenerate Secret». Dos detalles de la documentación importan:

  • Definir un secreto por primera vez activa la cabecera X-Signature en todos los webhooks salientes. Asegúrese de que su servidor acepta la nueva cabecera y la verifica antes de confiar en ella.
  • Un secreto regenerado surte efecto de inmediato. Actualice su manejador antes de hacer clic, o al mismo tiempo, de lo contrario las notificaciones válidas fallarán la verificación.

¿Cómo se construye la firma?

El procedimiento documentado tiene tres pasos. Lea el campo txid de la carga del webhook. Calcule HMAC-SHA256 usando su secreto personal como clave y la cadena txid como mensaje. Codifique el resultado en Base64 y compárelo con la cabecera. Una carga tiene este aspecto (de la guía de webhooks):

{
"id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed",
"webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8",
"from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN",
"to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM",
"blocknumber": "65542464",
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988",
"amount": 108935
}

¿Cómo se verifica la firma en su servidor?

Recalcule el HMAC a partir del txid y compárelo con la cabecera en tiempo constante. El siguiente manejador de Express lo hace. Lee el secreto de una variable de entorno, rechaza una cabecera ausente o de tamaño incorrecto, y responde 200 solo a las peticiones válidas:

const crypto = require('crypto');
const express = require('express');
const app = express();
app.use(express.json());
function isValid(txid, received, secret) {
const expected = crypto.createHmac('sha256', secret).update(txid).digest('base64');
const a = Buffer.from(expected);
const b = Buffer.from(received || '');
// timingSafeEqual throws when lengths differ, so check first
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/hooks/deposit', (req, res) => {
const ok = isValid(req.body.txid, req.get('X-Signature'), process.env.CG_PERSONAL_SECRET);
if (!ok) return res.sendStatus(401);
// process req.body.txid, deduplicate on it, then acknowledge
res.sendStatus(200);
});
app.listen(3000);

La documentación también incluye versiones en Python, Java y PHP. En Python, use hmac.compare_digest para la comparación. En Node.js, crypto.timingSafeEqual hace el mismo trabajo. Una comparación con == simple puede filtrar información por el tiempo de respuesta.

¿Cómo se prueba el manejador?

Calcule una firma usted mismo y envíe una notificación falsa a su servidor local. El comando openssl de abajo produce el mismo HMAC en Base64 que espera el manejador. Use un secreto de prueba, nunca el real:

Terminal window
TXID=18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988
SIG=$(printf '%s' "$TXID" | openssl dgst -sha256 -hmac "test-secret" -binary | base64)
curl -i -X POST http://localhost:3000/hooks/deposit \
-H "Content-Type: application/json" \
-H "X-Signature: $SIG" \
-d "{\"txid\": \"$TXID\"}"

Inicie el servidor con CG_PERSONAL_SECRET=test-secret. La petición devuelve 200. Cambie un solo carácter del secreto o de la firma, y devuelve 401. Repita esta prueba después de cada despliegue del manejador, y de nuevo tras regenerar su secreto real.

¿Qué no cubre la firma?

Cubre el ID de la transacción y nada más. Según la construcción documentada, solo txid entra en el HMAC. De ello se derivan dos consecuencias:

  • Una firma válida demuestra que Chaingateway envió una notificación para esa transacción. No demuestra que amount, to o contractaddress del cuerpo no hayan cambiado. Si esos campos deciden un pago saliente, compruébelos contra la cadena o contra los valores esperados del pedido.
  • La misma transacción puede llegar más de una vez, por ejemplo después de pedir que se reenvíe una notificación fallida, y cada copia tiene la misma firma válida. Elimine duplicados por txid.

Los webhooks no se reintentan automáticamente. Las notificaciones fallidas se listan por cadena, y usted solicita el reenvío de cada una. Solana no tiene webhooks. Donde existen webhooks, la firma funciona igual en todas las cadenas.

¿Cómo se rota el secreto sin perder notificaciones?

Un secreto regenerado surte efecto de inmediato, así que el orden de los pasos importa. Haga que el manejador acepte dos secretos durante un periodo breve, y después regenere:

  1. Despliegue una versión del manejador que pruebe primero el secreto actual y, si la primera comprobación falla, un segundo CG_PERSONAL_SECRET_NEXT opcional.
  2. Regenere el secreto en su perfil y copie el nuevo valor.
  3. Coloque el nuevo valor en CG_PERSONAL_SECRET_NEXT y vuelva a desplegar.
  4. Envíe una transferencia de prueba en testnet y confirme que el manejador la acepta.
  5. Pasado un día, promueva el nuevo secreto a CG_PERSONAL_SECRET y elimine el antiguo.

La documentación no indica qué secreto firma una notificación que reenvía después de una rotación. Mantenga abierta la ventana de dos secretos hasta que la lista de notificaciones fallidas esté vacía.

¿Qué ocurre si no ha definido un secreto?

Entonces los webhooks se envían sin la cabecera X-Signature. Su manejador no debe considerar válida una cabecera ausente. Decida por entorno: en producción, rechace las peticiones sin firma una vez que haya definido un secreto, y en un entorno de pruebas local puede permitirlas. La cabecera es también la forma de saber si hay un secreto activo: una notificación sin ella significa que no hay ningún secreto definido en su cuenta.

¿Dónde está la referencia completa?

La guía de seguridad de webhooks enumera los pasos y el código en cuatro lenguajes, y la guía de webhooks explica cómo crear webhooks y receptores.

Cómo escribimos estos artículos

¿Listo para construirlo tú mismo? Obtenga su clave de API — prueba de 7 días, sin tarjeta — o consulte API Blockchain para la referencia completa de los endpoints.

C
Chaingateway Team
Expertos en blockchain

El equipo de Chaingateway se dedica a simplificar la integración blockchain para desarrolladores de todo el mundo.