Защита вебхуков

Защита вебхуков

Обзор

Чтобы обеспечить подлинность и целостность вебхуков, мы предоставляем заголовок X-Signature, который можно проверить. Этот заголовок содержит подпись, сгенерированную с использованием вашего personal_secret, которую вы можете проверить, чтобы подтвердить, что запрос вебхука является подлинным и не был изменён.

Важные замечания

• Установка личного секрета: Если у вас ещё не установлен личный секрет, учтите, что добавление такового включит заголовок X-Signature во всех исходящих вебхуках. Убедитесь, что ваш сервер может принимать и проверять этот заголовок.
• Обновление личного секрета: Если у вас уже есть личный секрет и вы решите его изменить, новый секрет немедленно вступит в силу для уведомлений вебхуков. Убедитесь, что ваш сервер обновлён для использования нового секрета, чтобы избежать сбоев.

Установка личного секрета

Вы можете установить или сгенерировать заново свой личный секрет, перейдя в настройки профиля на нашей платформе. Выполните следующие шаги:

1. Перейдите в настройки профиля: Настройки профиля
2. Найдите раздел личного секрета: Найдите раздел с надписью «Personal Secret».
3. Установите или сгенерируйте заново секрет:
   • Если секрет не установлен, нажмите «Set Personal Secret», чтобы сгенерировать новый секрет.
   • Если секрет уже присутствует, нажмите «Regenerate Secret», чтобы создать новый.

Как формируется заголовок X-Signature

Извлечение txid из payload:

txid (идентификатор транзакции) — это уникальный идентификатор, включённый в payload вебхука. Этот ID используется как часть процесса генерации подписи. Объединение txid с личным секретом:

Личный секрет — это общий секретный ключ, известный только отправителю (например, провайдеру вебхука) и получателю (вашему приложению). Этот секретный ключ гарантирует, что подпись может быть сгенерирована и проверена только сторонами, которые знают секрет. Генерация HMAC (Hash-based Message Authentication Code):

HMAC — это специальный тип кода аутентификации сообщений (MAC), который использует криптографическую хеш-функцию и секретный ключ. В данном случае txid и личный секрет используются для генерации HMAC. HMAC обычно генерируется с использованием алгоритма хеширования, например SHA-256.

Проверка заголовка X-Signature

Когда вы получаете вебхук, важно проверить заголовок X-Signature, чтобы убедиться, что запрос поступил из доверенного источника. Ниже приведены примеры того, как выполнить эту проверку на Python, Java, PHP и 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.");
}

Заключение

Благодаря возможности управлять своим personal_secret, у вас есть расширенный контроль над безопасностью ваших вебхуков. Всегда следите за тем, чтобы обработчик вебхуков вашего сервера обновлялся каждый раз при изменении personal_secret, чтобы избежать сбоев в обслуживании. Если у вас есть вопросы или проблемы, обратитесь в поддержку.