Webhooks: подписанные данные и повторные попытки
Вы создали 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
Лучшие практики:
- Используйте надежный секрет и периодически меняйте его.
- Включайте метку времени в подписываемые данные для предотвращения атак повторного воспроизведения.
- Используйте
hmac.compare_digestдля сравнения за постоянное время. - Подписывайте исходное тело, а не проанализированный JSON, чтобы избежать несоответствий.
Реализация надежных повторных попыток
Доставка вебхуков может не удаться из-за проблем с сетью, простоя получателя или ошибок обработки. Надежная система должна повторять неудачные доставки с экспоненциальной задержкой.
Стратегия повторных попыток
Распространенный подход: повторять до 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) | Высокая | Средняя | Да (с меткой времени) |
Пошаговое руководство: создание отправителя вебхуков с повторными попытками
- Определите данные события и включите уникальный идентификатор события и метку времени.
- Вычислите подпись с помощью HMAC-SHA256 по исходному телу.
- Отправьте запрос с подписью в заголовке.
- Обрабатывайте сбои, повторяя попытки с экспоненциальной задержкой.
- Регистрируйте доставки и обеспечьте видимость.
Тестирование вебхуков
Используйте такие инструменты, как ngrok, чтобы открыть доступ к локальному серверу и протестировать доставку вебхуков. Всегда проверяйте подписи в тестах, чтобы выявлять проблемы на ранней стадии.
Часто задаваемые вопросы
Что такое подписанные данные в вебхуках?
Подписанные данные — это запрос вебхука, в котором отправитель включает криптографическую подпись (обычно HMAC), сгенерированную с использованием общего секрета. Получатель проверяет подпись, чтобы подтвердить, что запрос подлинный и не был изменен.
Сколько раз следует повторять неудачный вебхук?
Фиксированного числа нет, но распространенная практика — от 3 до 5 повторных попыток с экспоненциальной задержкой. Учитывайте типичное время простоя получателя и критичность события. Всегда разрешайте ручные повторные попытки.
Можно ли использовать JWT для подписей вебхуков?
Да, JWT можно использовать, но это сложнее. Подписи HMAC проще и достаточны для большинства случаев. Если вам нужно включить утверждения, JWT может подойти.
Готовы протестировать данные ваших вебхуков? Используйте наш JSON Formatter, чтобы проверить и отформатировать ваши JSON-данные перед отправкой.