Proteger los webhooks

Proteger los webhooks

Descripción general

Para garantizar la autenticidad e integridad de los webhooks, proporcionamos una cabecera X-Signature que se puede validar. Esta cabecera contiene una firma generada mediante su personal_secret, que puede verificar para confirmar que la solicitud de webhook es legítima y no ha sido manipulada.

Notas importantes

• Configurar un secreto personal: Si aún no tiene configurado un secreto personal, tenga en cuenta que añadir uno activará la cabecera X-Signature en todos los webhooks salientes. Asegúrese de que su servidor pueda aceptar y verificar esta cabecera.
• Renovar su secreto personal: Si ya tiene un secreto personal y decide cambiarlo, el nuevo secreto tendrá efecto inmediato en las notificaciones de webhook. Asegúrese de que su servidor se actualice para usar el nuevo secreto y evitar interrupciones.

Configurar el secreto personal

Puede configurar o regenerar su secreto personal accediendo a la configuración de su perfil en nuestra plataforma. Siga estos pasos:

1. Vaya a la configuración del perfil: Configuración del perfil
2. Localice la sección del secreto personal: Busque la sección etiquetada como «Personal Secret».
3. Configure o regenere el secreto:
   • Si no hay ningún secreto configurado, haga clic en «Set Personal Secret» para generar uno nuevo.
   • Si ya hay un secreto presente, haga clic en «Regenerate Secret» para crear uno nuevo.

Cómo se construye la cabecera X-Signature

Extraer el txid del payload:

El txid (identificador de transacción) es un identificador único incluido en el payload del webhook. Este ID se utiliza como parte del proceso de generación de la firma. Combinar el txid con un secreto personal:

El secreto personal es una clave secreta compartida conocida solo por el emisor (por ejemplo, el proveedor del webhook) y el receptor (su aplicación). Esta clave secreta garantiza que la firma solo pueda ser generada y verificada por las partes que conocen el secreto. Generar el HMAC (Hash-based Message Authentication Code):

HMAC es un tipo específico de código de autenticación de mensajes (MAC) que utiliza una función hash criptográfica y una clave secreta. En este caso, el txid y el secreto personal se utilizan para generar el HMAC. El HMAC normalmente se genera utilizando un algoritmo de hash como SHA-256.

Verificar la cabecera X-Signature

Cuando reciba un webhook, es esencial verificar la cabecera X-Signature para asegurarse de que la solicitud proviene de una fuente confiable. A continuación se muestran ejemplos de cómo realizar esta verificación en Python, Java, PHP y JavaScript.

Python

import hmac
import hashlib
import base64

def verify_signature(txid, received_signature, personal_secret):
    # Generate the expected signature
    expected_signature = base64.b64encode(hmac.new(
        personal_secret.encode(),
        txid.encode(),
        hashlib.sha256
    ).digest()).decode()

    # Compare the expected signature with the received signature
    return hmac.compare_digest(expected_signature, received_signature)

# Example usage
txid = 'your_txid_here'
received_signature = 'received_signature_here'
personal_secret = 'your_personal_secret_here'

if verify_signature(txid, received_signature, personal_secret):
    print("Signature is valid.")
else:
    print("Invalid signature.")

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class SignatureVerifier {
    public static boolean verifySignature(String txid, String receivedSignature, String personalSecret) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(personalSecret.getBytes(), "HmacSHA256");
        mac.init(secretKeySpec);

        byte[] signatureBytes = mac.doFinal(txid.getBytes());
        String expectedSignature = Base64.getEncoder().encodeToString(signatureBytes);

        return expectedSignature.equals(receivedSignature);
    }

    public static void main(String[] args) {
        try {
            String txid = "your_txid_here";
            String receivedSignature = "received_signature_here";
            String personalSecret = "your_personal_secret_here";

            if (verifySignature(txid, receivedSignature, personalSecret)) {
                System.out.println("Signature is valid.");
            } else {
                System.out.println("Invalid signature.");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

PHP

function verifySignature($txid, $receivedSignature, $personalSecret) {
    // Generate the expected signature
    $expectedSignature = base64_encode(hash_hmac('sha256', $txid, $personalSecret, true));

    // Compare the expected signature with the received signature
    return hash_equals($expectedSignature, $receivedSignature);
}

// Example usage
$txid = 'your_txid_here';
$receivedSignature = 'received_signature_here';
$personalSecret = 'your_personal_secret_here';

if (verifySignature($txid, $receivedSignature, $personalSecret)) {
    echo "Signature is valid.";
} else {
    echo "Invalid signature.";
}

JavaScript

const crypto = require('crypto');

function verifySignature(txid, receivedSignature, personalSecret) {
    // Generate the expected signature
    const expectedSignature = crypto
        .createHmac('sha256', personalSecret)
        .update(txid)
        .digest('base64');

    // Compare the expected signature with the received signature
    return crypto.timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(receivedSignature));
}

// Example usage
const txid = 'your_txid_here';
const receivedSignature = 'received_signature_here';
const personalSecret = 'your_personal_secret_here';

if (verifySignature(txid, receivedSignature, personalSecret)) {
    console.log("Signature is valid.");
} else {
    console.log("Invalid signature.");
}

Conclusión

Con la posibilidad de gestionar su personal_secret, dispone de un mayor control sobre la seguridad de sus webhooks. Asegúrese siempre de que el gestor de webhooks de su servidor se actualice cada vez que cambie el personal_secret para evitar interrupciones del servicio. Si tiene alguna pregunta o problema, póngase en contacto con soporte.