Вебхуки: подписанные данные и повторные попытки

Почему вебхуки одновременно мощны и хрупки

Вебхуки обеспечивают интеграции в реальном времени: уведомления о платежах, триггеры CI/CD, сообщения в чатах. Но с ними связаны две большие проблемы: безопасность (как узнать, что запрос пришел от ожидаемого отправителя?) и надежность (что, если получатель недоступен?). Эта статья покажет, как решить обе проблемы с помощью подписанных данных и стратегий повторных попыток.

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

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

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

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

Как генерировать и проверять подписи

Вот типичный процесс:

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

Пример на Node.js:

const crypto = require('crypto');

function verifySignature(secret, payload, signature) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const digest = hmac.digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}

Всегда используйте сравнение с постоянным временем, чтобы предотвратить атаки по времени. Никогда не анализируйте тело до проверки — используйте промежуточное ПО для исходного тела.

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

Даже с подписями сбои сети или временные отключения могут привести к неудачной доставке вебхука. Надежный механизм повторных попыток обеспечивает eventual delivery.

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

• Экспоненциальная задержка: Увеличивайте время ожидания между попытками (например, 1с, 2с, 4с, 8с).
• Максимальное количество попыток: Ограничьте повторные попытки (например, 5 попыток), чтобы избежать бесконечных циклов.
• Очередь недоставленных сообщений: После максимального количества попыток сохраните событие для ручной проверки.
• Идемпотентность: Включите уникальный идентификатор события, чтобы потребитель мог игнорировать дубликаты.

Пример логики повторных попыток на Python:

import time
import requests

def send_webhook(url, payload, max_retries=5):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, timeout=5)
            if response.status_code == 200:
                return True
        except requests.RequestException:
            pass
        time.sleep(2 ** attempt)  # экспоненциальная задержка
    return False

Лучшие практики для потребителей вебхуков

• Отвечайте 2xx быстро; при необходимости обрабатывайте асинхронно.
• Проверяйте подпись перед любой обработкой.
• Используйте ключи идемпотентности для обработки дублирующихся доставок.
• Логируйте все входящие вебхуки для отладки.
• Следите за сбоями и оповещайте о повторяющихся ошибках.

Сравнение: опрос vs вебхуки

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

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

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

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

Универсального числа нет, но обычно это 3–5 попыток с экспоненциальной задержкой. После этого залогируйте событие для ручной проверки.

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

Да, некоторые провайдеры используют JWT. Принцип тот же: проверьте подпись и утверждения токена, прежде чем доверять данным.

Нужно проверить данные или логи вебхуков? Попробуйте наш JSON Formatter, чтобы быстро отформатировать и проверить JSON.