Верификация подписи
Подпись уведомления создаётся асимметричным ключом на стороне Pert и передаётся в заголовке
X-Webhook-Signature в base64 и позволяет вам убедиться, что запрос пришёл именно от Pert и тело не было изменено.
| Параметр | Значение |
|---|---|
| Алгоритм | ECDSA на кривой SECP256K1 |
| Хеш-функция | SHA-256 |
| Формат подписи | DER-encoded ASN.1 (r, s), затем base64 |
| Что подписано | Сырые байты тела HTTP-запроса |
Всегда проверяйте подпись
Подпись — это единственная гарантия того, что запрос пришёл от Pert. Никогда не доверяйте полям тела
(event_id, data и т. д.) до успешной верификации. Запросы с невалидной подписью отбрасывайте с кодом
401 Unauthorized и логируйте. При недоступности подписания запрос может
прийти без подписи — его тоже нужно отклонить.
Получение публичного ключа
Эндпоинт открыт без авторизации:
curl https://gateway.pert.paranoid.security/api/v1/webhooks/signing-key
Ответ:
{
"public_key": "LS0tLS1CRUdJTi...(base64-кодированный PEM)...LS0tLS0K",
"algorithm": "ECDSA-SECP256K1-SHA256"
}
Поле public_key — это PEM-кодированный публичный ключ, дополнительно завёрнутый в base64. Чтобы получить
PEM-строку, декодируйте public_key из base64.
Кешируйте публичный ключ
Публичный ключ редко меняется. Получите его один раз при старте приложения и кешируйте — нет смысла запрашивать его при каждой доставке.
Алгоритм проверки
- Получите публичный ключ с
/api/v1/webhooks/signing-keyи декодируйте его из base64 в PEM. - Декодируйте
X-Webhook-Signatureиз base64 в байты подписи. - Проверьте подпись над точными байтами тела HTTP-запроса с помощью публичного ключа.
Подпись над сырыми байтами
Подпись считается над сырыми байтами тела, как они пришли по сети. Не пересериализуйте JSON, не меняйте порядок ключей, не удаляйте/добавляйте пробелы — всё это сломает верификацию.
В большинстве веб-фреймворков для этого нужен доступ к raw body до парсинга JSON:
| Фреймворк | Как получить raw body |
|---|---|
| Express | express.raw({ type: "application/json" }) |
| Flask | request.get_data() (вместо request.get_json()) |
| FastAPI | await request.body() |
Go net/http |
io.ReadAll(r.Body) до парсинга |
Примеры
DER-подпись требует sigdecode_der.
import base64
import hashlib
from ecdsa import VerifyingKey, BadSignatureError, MalformedPointError, SECP256k1
from ecdsa.der import UnexpectedDER
from ecdsa.util import sigdecode_der
def verify_webhook(body: bytes, signature_b64: str, public_key_b64: str) -> bool:
"""Проверяет подпись webhook-уведомления."""
try:
public_key_pem = base64.b64decode(public_key_b64, validate=True).decode("utf-8")
vk = VerifyingKey.from_pem(public_key_pem)
if vk.curve != SECP256k1:
return False
signature = base64.b64decode(signature_b64, validate=True)
vk.verify(signature, body, hashfunc=hashlib.sha256, sigdecode=sigdecode_der)
return True
except (BadSignatureError, MalformedPointError, UnexpectedDER, ValueError):
return False
import crypto from "node:crypto";
function verifyWebhook(rawBody, signatureB64, publicKeyB64) {
const pem = Buffer.from(publicKeyB64, "base64").toString("utf8");
const signature = Buffer.from(signatureB64, "base64");
const verifier = crypto.createVerify("sha256");
verifier.update(rawBody);
verifier.end();
return verifier.verify(pem, signature);
}
Express
Используйте express.raw({ type: "application/json" }) для роута webhook, чтобы получить тело как
Buffer до парсинга JSON.
Для SECP256K1 используется github.com/decred/dcrd/dcrec/secp256k1/v4.
Стандартный x509.ParsePKIXPublicKey эту кривую не разбирает.
import (
"crypto/sha256"
"crypto/x509/pkix"
"encoding/asn1"
"encoding/base64"
"encoding/pem"
"github.com/decred/dcrd/dcrec/secp256k1/v4"
k1ecdsa "github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa"
)
func verifyWebhook(body []byte, signatureB64, publicKeyB64 string) bool {
pemBytes, err := base64.StdEncoding.DecodeString(publicKeyB64)
if err != nil { return false }
block, _ := pem.Decode(pemBytes)
if block == nil || block.Type != "PUBLIC KEY" { return false }
var spki struct {
Algorithm pkix.AlgorithmIdentifier
PublicKey asn1.BitString
}
rest, err := asn1.Unmarshal(block.Bytes, &spki)
if err != nil || len(rest) != 0 { return false }
if !spki.Algorithm.Algorithm.Equal(asn1.ObjectIdentifier{1, 2, 840, 10045, 2, 1}) {
return false
}
var curve asn1.ObjectIdentifier
rest, err = asn1.Unmarshal(spki.Algorithm.Parameters.FullBytes, &curve)
if err != nil || len(rest) != 0 || !curve.Equal(asn1.ObjectIdentifier{1, 3, 132, 0, 10}) {
return false
}
pub, err := secp256k1.ParsePubKey(spki.PublicKey.Bytes)
if err != nil { return false }
signature, err := base64.StdEncoding.DecodeString(signatureB64)
if err != nil { return false }
sig, err := k1ecdsa.ParseDERSignature(signature)
if err != nil { return false }
hash := sha256.Sum256(body)
return sig.Verify(hash[:], pub)
}
Используется провайдер Bouncy Castle
(org.bouncycastle:bcprov-jdk18on) с поддержкой SECP256K1.
import java.security.*;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
import org.bouncycastle.jce.provider.BouncyCastleProvider;
public class WebhookVerifier {
public static boolean verify(byte[] body, String signatureB64, String publicKeyB64)
throws Exception {
byte[] pemBytes = Base64.getDecoder().decode(publicKeyB64);
String pem = new String(pemBytes)
.replace("-----BEGIN PUBLIC KEY-----", "")
.replace("-----END PUBLIC KEY-----", "")
.replaceAll("\\s+", "");
byte[] keyBytes = Base64.getDecoder().decode(pem);
Provider provider = new BouncyCastleProvider();
KeyFactory kf = KeyFactory.getInstance("EC", provider);
PublicKey publicKey = kf.generatePublic(new X509EncodedKeySpec(keyBytes));
Signature sig = Signature.getInstance("SHA256withECDSA", provider);
sig.initVerify(publicKey);
sig.update(body);
return sig.verify(Base64.getDecoder().decode(signatureB64));
}
}
Production-ready код
Эти примеры даны для справки. В production добавьте:
- обработку ошибок и логирование отказов;
- ограничение размера принимаемого тела (например, 1 МБ);
- тайм-аут на верификацию;
- отдельный URL получателя для каждого workspace и проверку контекста:
X-Webhook-Workspace-Idне входит в подписанное тело; - аудит-лог запросов с невалидной подписью.
Что делать при ошибке верификации
| Ситуация | Что делать |
|---|---|
| Подпись не совпадает | Вернуть 401, логировать заголовки и факт отказа (без тела) |
Заголовок X-Webhook-Signature пустой |
Вернуть 401. Это может быть запрос не от Pert |
| Не удалось получить/распарсить ключ | Вернуть 503, попробовать получить ключ снова |
Workspace в X-Webhook-Workspace-Id не ваш |
Вернуть 400, событие чужое |