Перейти к содержанию

Верификация подписи

Подпись уведомления создаётся асимметричным ключом на стороне 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.

Кешируйте публичный ключ

Публичный ключ редко меняется. Получите его один раз при старте приложения и кешируйте — нет смысла запрашивать его при каждой доставке.

Алгоритм проверки

  1. Получите публичный ключ с /api/v1/webhooks/signing-key и декодируйте его из base64 в PEM.
  2. Декодируйте X-Webhook-Signature из base64 в байты подписи.
  3. Проверьте подпись над точными байтами тела 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, событие чужое