Webhooks: подписанные данные и повторные попытки

Backend2026-11-14TryQuickToolBox

Вы создали API, и теперь нужно уведомлять другие сервисы о происходящих событиях. Опрос неэффективен, поэтому вы реализуете вебхуки. Но вскоре понимаете: как убедиться, что данные подлинные? Что, если получатель недоступен? Без надлежащих мер защиты вебхуки могут стать дырой в безопасности и источником проблем с надежностью.

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

Что такое вебхуки?

Вебхуки — это определяемые пользователем HTTP-обратные вызовы. Они позволяют одной системе отправлять данные в реальном времени другой системе при возникновении определенного события. В отличие от API, где вы запрашиваете данные, вебхуки отправляют данные вам. Это делает их идеальными для событийно-ориентированных архитектур.

Распространенные случаи использования включают уведомления о платежах (например, Stripe), триггеры CI/CD (например, GitHub) и платформы обмена сообщениями (например, Slack). Отправитель выполняет HTTP POST-запрос на URL, предоставленный получателем, с данными, содержащими подробности события.

Зачем защищать вебхуки с помощью подписанных данных?

Конечные точки вебхуков общедоступны, что делает их уязвимыми для подделки. Злоумышленник может отправить поддельные данные, чтобы вызвать нежелательные действия. Чтобы предотвратить это, отправители подписывают данные, используя общий секрет. Получатель проверяет подпись, чтобы убедиться в подлинности и целостности.

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

Как реализовать подписанные данные

Рассмотрим простой пример на Python с использованием Flask. Отправитель вычисляет подпись:

import hmac
import hashlib
import json
import requests

secret = b'your_shared_secret'
payload = {'event': 'payment.success', 'amount': 100}
body = json.dumps(payload).encode('utf-8')
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()

headers = {'Content-Type': 'application/json', 'X-Signature': signature}
requests.post('https://receiver.com/webhook', data=body, headers=headers)

Получатель проверяет подпись:

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

app = Flask(__name__)
secret = b'your_shared_secret'

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature')
    body = request.get_data()
    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)
    # Process payload
    return '', 200

Лучшие практики:

Реализация надежных повторных попыток

Доставка вебхуков может не удаться из-за проблем с сетью, простоя получателя или ошибок обработки. Надежная система должна повторять неудачные доставки с экспоненциальной задержкой.

Стратегия повторных попыток

Распространенный подход: повторять до N раз с увеличивающимися задержками (например, 1 с, 5 с, 30 с, 5 мин, 30 мин). После исчерпания попыток пометить доставку как неудачную и оповестить.

Вот простой механизм повторных попыток на Python с использованием библиотек requests и tenacity:

from tenacity import retry, stop_after_attempt, wait_exponential
import requests

@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=1, max=60))
def send_webhook(url, payload, signature):
    headers = {'X-Signature': signature}
    response = requests.post(url, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return response

Лучшие практики для повторных попыток:

Сравнение: подписанные данные против базовой аутентификации

ПодходБезопасностьСложностьЗащита от повторного воспроизведения
Базовая аутентификацияНизкая (учетные данные отправляются каждый раз)НизкаяНет
Подписанные данные (HMAC)ВысокаяСредняяДа (с меткой времени)

Пошаговое руководство: создание отправителя вебхуков с повторными попытками

  1. Определите данные события и включите уникальный идентификатор события и метку времени.
  2. Вычислите подпись с помощью HMAC-SHA256 по исходному телу.
  3. Отправьте запрос с подписью в заголовке.
  4. Обрабатывайте сбои, повторяя попытки с экспоненциальной задержкой.
  5. Регистрируйте доставки и обеспечьте видимость.

Тестирование вебхуков

Используйте такие инструменты, как ngrok, чтобы открыть доступ к локальному серверу и протестировать доставку вебхуков. Всегда проверяйте подписи в тестах, чтобы выявлять проблемы на ранней стадии.

Часто задаваемые вопросы

Что такое подписанные данные в вебхуках?

Подписанные данные — это запрос вебхука, в котором отправитель включает криптографическую подпись (обычно HMAC), сгенерированную с использованием общего секрета. Получатель проверяет подпись, чтобы подтвердить, что запрос подлинный и не был изменен.

Сколько раз следует повторять неудачный вебхук?

Фиксированного числа нет, но распространенная практика — от 3 до 5 повторных попыток с экспоненциальной задержкой. Учитывайте типичное время простоя получателя и критичность события. Всегда разрешайте ручные повторные попытки.

Можно ли использовать JWT для подписей вебхуков?

Да, JWT можно использовать, но это сложнее. Подписи HMAC проще и достаточны для большинства случаев. Если вам нужно включить утверждения, JWT может подойти.

Готовы протестировать данные ваших вебхуков? Используйте наш JSON Formatter, чтобы проверить и отформатировать ваши JSON-данные перед отправкой.