Алгоритм подписи Avito Webhook: HMAC-SHA256 руководство

Для формирования подписи ‘x-avito-messenger-signature’ в webhook API Avito используется алгоритм HMAC с хэш-функцией SHA-256. Подпись генерируется путем вычисления HMAC-хэша от тела запроса с использованием секретного ключа, предоставляемого Avito, и сравнения полученного значения с подписью, переданной в заголовке запроса.

Содержание

• Алгоритм генерации подписи
• Процесс верификации
• Примеры реализации
• Рекомендации по безопасности
• Типичные проблемы и решения

Алгоритм генерации подписи

Подпись ‘x-avito-messenger-signature’ формируется с использованием криптографического алгоритма HMAC (Hash-based Message Authentication Code) с хэш-функцией SHA-256.

Принцип работы HMAC

HMAC - это механизм аутентификации сообщений, который использует криптографическую хэш-функцию вместе с секретным ключом для обеспечения целостности и подлинности данных. В случае с Avito webhook API, процесс выглядит следующим образом:

1. Секретный ключ: Avito предоставляет вам секретный ключ, который должен храниться в безопасности и никогда не передаваться третьим лицам.

2. Тело запроса: В качестве сообщения для хэширования используется тело HTTP-запроса (payload).

3. Хэширование: Выполняется HMAC-хэширование с использованием SHA-256:

   signature = HMAC-SHA256(secret_key, payload)
   

4. Форматирование: Полученный хэш форматируется в виде строки с префиксом “sha256=”:

   formatted_signature = "sha256=" + hex(digest)
   

Структура заголовка

Заголовок ‘x-avito-messenger-signature’ содержит подпись в следующем формате:

x-avito-messenger-signature: sha256=ваш_хэш_в_hex_формате

Процесс верификации

Для проверки подлинности входящих запросов от Avito необходимо выполнить следующие шаги:

Шаг 1: Извлечение данных

1. Получите значение заголовка x-avito-messenger-signature из HTTP-запроса
2. Сохраните тело запроса в исходном виде (без изменений)
3. Используйте секретный ключ, предоставленный Avito

Шаг 2: Генерация ожидаемой подписи

1. Выполните HMAC-SHA256 хэширование тела запроса с использованием секретного ключа
2. Преобразуйте результат в шестнадцатеричную строку
3. Добавьте префикс “sha256=” к результату

Шаг 3: Сравнение подписей

1. Сравните сгенерированную подпись с полученной из заголовка
2. Используйте безопасное сравнение (timing-safe comparison) для предотвращения атак по времени

Важно: При сравнении подписей всегда используйте специализированные функции безопасного сравнения, а не простое строковое сравнение, чтобы предотвратить атаки по времени (timing attacks).

Примеры реализации

Python реализация

import hmac
import hashlib
import json

def verify_avito_signature(payload, signature, secret_key):
    """
    Verify Avito webhook signature
    
    :param payload: Raw request body bytes
    :param signature: Signature from x-avito-messenger-signature header
    :param secret_key: Secret key provided by Avito
    :return: True if signature is valid, False otherwise
    """
    # Generate expected signature
    digest = hmac.new(
        secret_key.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    expected_signature = f"sha256={digest}"
    
    # Use timing-safe comparison
    return hmac.compare_digest(signature, expected_signature)

# Flask example
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.post('/webhook')
def webhook_handler():
    # Get signature from header
    signature = request.headers.get('x-avito-messenger-signature')
    
    # Get raw body
    payload = request.get_data()
    
    # Your secret key from Avito
    AVITO_SECRET_KEY = 'your-secret-key-here'
    
    # Verify signature
    if not verify_avito_signature(payload, signature, AVITO_SECRET_KEY):
        return jsonify({'error': 'Invalid signature'}), 401
    
    # Process webhook data
    data = request.get_json()
    
    # Your business logic here
    return jsonify({'status': 'success'}), 200

JavaScript (Node.js) реализация

const crypto = require('crypto');

function verifyAvitoSignature(payload, signature, secretKey) {
    // Generate expected signature
    const hmac = crypto.createHmac('sha256', secretKey);
    hmac.update(payload);
    const digest = hmac.digest('hex');
    const expectedSignature = `sha256=${digest}`;
    
    // Use timing-safe comparison
    return crypto.timingSafeEqual(
        Buffer.from(signature, 'utf8'),
        Buffer.from(expectedSignature, 'utf8')
    );
}

// Express.js example
const express = require('express');
const app = express();

app.use(express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
    const signature = req.get('x-avito-messenger-signature');
    const payload = req.body;
    
    const AVITO_SECRET_KEY = 'your-secret-key-here';
    
    if (!verifyAvitoSignature(payload, signature, AVITO_SECRET_KEY)) {
        return res.status(401).json({ error: 'Invalid signature' });
    }
    
    const data = JSON.parse(payload.toString());
    
    // Your business logic here
    res.json({ status: 'success' });
});

Рекомендации по безопасности

Безопасное хранение секретных ключей

1. Не храните ключи в коде: Используйте переменные окружения или системы управления секретами
2. Регулярная ротация ключей: Периодически изменяйте секретные ключи
3. Ограниченный доступ: Предоставляйте доступ к ключам только необходимым системам

Защита от атак

1. HTTPS: Всегда используйте HTTPS для передачи webhook данных
2. IP-белые списки: Ограничьте прием запросов только от доверенных IP-адресов Avito
3. Логирование: Ведите логи всех проверок подписей для аудита

Производительность

1. Кэширование: Если возможно, кэшируйте результаты проверок для часто повторяющихся запросов
2. Асинхронная обработка: Обрабатывайте валидные запросы асинхронно для быстрого ответа Avito

Типичные проблемы и решения

Проблема: Несоответствие подписей

Симптом: Вы генерируете подпись, но она не совпадает с полученной от Avito.

Возможные причины:

• Неправильный секретный ключ
• Изменение тела запроса (добавление/удаление пробелов, изменение кодировки)
• Неверный форматирование подписи

Решения:

1. Проверьте правильность секретного ключа
2. Убедитесь, что используете исходное тело запроса без изменений
3. Проверьте формат подписи (должен быть префикс “sha256=”)

Проблема: Производительность

Симптом: Проверка подписей занимает слишком много времени.

Решения:

1. Используйте более эффективные криптографические библиотеки
2. Реализуйте параллельную обработку
3. Рассмотрите использование аппаратного ускорения для криптографических операций

Проблема: Безопасность

Симптом: Подозрения на взлом или компрометацию ключа.

Решения:

1. Немедленно смените секретный ключ
2. Проверьте логи на предмет подозрительной активности
3. Увеличьте частоту ротации ключей

Источники

1. Портал разработчика Авито - Messenger API
2. HMAC Webhook Authentication: Complete Guide + Code Examples
3. Webhook Signature Verification | IDaaS API Client Documentation
4. Authentication & Verification | Hookdeck Event Gateway Docs
5. HMAC Validation in ServiceNow: Securing Webhook Integrations with CertificateEncryption

Заключение

Понимание механизма генерации подписи ‘x-avito-messenger-signature’ критически важно для безопасной интеграции с webhook API Avito. Ключевые моменты:

1. Алгоритм: Используется HMAC-SHA256 для генерации подписи
2. Формат: Подписи всегда начинаются с префикса “sha256=”
3. Верификация: Требуется безопасное сравнение подписей для предотвращения атак по времени
4. Безопасность: Секретные ключи должны храниться в безопасности и регулярно ротироваться

Для успешной реализации рекомендуется тщательно протестировать механизм верификации в сред разработки перед развертыванием в production. Всегда используйте современные криптографические библиотеки и следуйте лучшим практикам безопасности при работе с webhook-запросами.