Подпись охватывает полный payload вебхука: id, delivered_at, event. Поддерживаются два алгоритма подписи в зависимости от keyType:
ED25519 (Рекомендуемый)
- Создать объект payload:
id, delivered_at, event
- JSON.stringify(payload)
- Закодировать JSON-строку в Base64
- Подписать с помощью ED25519 (ed25519.signAsync)
- Закодировать подпись в Base64
Legacy (Устаревший)
- Создать объект payload:
id, delivered_at, event
- JSON.stringify(payload)
- Закодировать JSON-строку в Base64
- SHA256 хеш (privateKey + data)
- Закодировать хеш в Base64
Особенности безопасности:
- Подпись охватывает все поля, включая id и delivered_at
- Уникальный id предотвращает атаки повторного воспроизведения (replay attacks)
- Валидация временной метки предотвращает принятие устаревших вебхуков (окно 16 минут)
- 16-минутное окно учитывает повторные попытки (немедленно + 5 мин + 10 мин) + сетевой буфер
- ED25519 обеспечивает криптографическую подлинность
Логика повторной попытки
- Первая попытка: Немедленно
- Вторая попытка: задержка в 300 секунд (5 минут)
- Третья попытка: задержка в 600 секунд (10 минут)
- Ошибка: задача удалена из очереди, логирована
ВАЖНО: Всегда проверяйте webhooks, чтобы предотвратить подделку и повторные атаки.
Полный алгоритм проверки
Этапы проверки ED25519
- Защита от повторного воспроизведения - Проверьте
webhook.id, который не был замечен ранее
- Проверка метки времени - проверка delivery_at в течение 16 минут (максимальное время доставки + буфер)
- Восстановление полезной нагрузки -
id, delivery_at, event
- Проверка подписи - ed25519.verifyAsync (signature, payload, publicKey)
- Сохранить идентификатор веб-узла - сохранить для предотвращения повторного воспроизведения