Webhook imzasını doğrulayın

MailGraf, her webhook teslimine HMAC imzası ekler. Gönderilen veriye güvenmeden önce imzayı doğrulayın. Böylece üçüncü bir taraf aynı endpointe sahte olay gönderemez.

İmza bilgilerini alın

Ayarlar > Webhook bölümünde endpointi açın. İmza anahtarı yanındaki Göster seçeneğine tıklayın, whsec_ ile başlayan değeri kopyalayın ve karşı servisin gizli anahtar yöneticisinde saklayın. Anahtarı kaynak koda veya loglara eklemeyin.

Her istek şu başlığı taşır:

X-MailGraf-Signature: t=<unix_timestamp>,v1=<hex_signature>

MailGraf isteğin hiç değiştirilmemiş gövdesini HMAC-SHA256 ile imzalar. İmzalanan mesajın yapısı şöyledir:

<timestamp>.<raw_request_body>

JSON verisinden önce doğrulayın

1. Ham gövdeyi alın

   İstek gövdesini JSON ayrıştırıcısı veya ara katman değiştirmeden önce bayt olarak alın.

2. t ve v1 değerlerini okuyun

   X-MailGraf-Signature başlığını zaman damgası ve onaltılık imza olarak ayırın.

3. Beklenen imzayı hesaplayın

   Zaman damgasını, noktayı ve ham gövdeyi birleştirin. Bu değeri endpointin imza anahtarıyla HMAC-SHA256 kullanarak imzalayın.

4. Sabit sürede karşılaştırın

   Beklenen imzayı gelen imzayla zamanlama saldırılarına dayanıklı bir fonksiyon kullanarak karşılaştırın. Olayı yalnızca değerler eşleşirse işleyin.

Node.js

Değiştirilmemiş gövdeyi Buffer olarak verin:

const crypto = require("crypto");

function verifyMailGrafSignature(secret, signatureHeader, rawBody) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => part.trim().split("=", 2))
  );

  if (!parts.t || !parts.v1) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.`)
    .update(rawBody)
    .digest();
  const received = Buffer.from(parts.v1, "hex");

  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(received, expected)
  );
}

Python

Değiştirilmemiş gövdeyi bytes olarak verin:

import hashlib
import hmac


def verify_mailgraf_signature(secret, signature_header, raw_body):
    parts = dict(
        part.strip().split("=", 1) for part in signature_header.split(",")
    )
    timestamp = parts.get("t")
    received = parts.get("v1")
    if not timestamp or not received:
        return False

    message = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

Doğrulamadan sonra uzun sürecek işlemleri kuyruğa alın ve yedi saniye içinde 2xx yanıtı verin. Karşı servis işlemi daha sonra tamamlasa bile MailGraf daha geç gelen yanıtı başarısız teslim sayar.

İmza anahtarını yenileyin

Anahtarın açığa çıkmış olabileceği durumlarda veya kendi güvenlik planınıza göre Yenile seçeneğini kullanın. Yenileme, eski anahtarı hemen geçersiz kılar. Yeni değeri kopyalayın, karşı servisi güncelleyin ve değişikliği doğrulamak için Test olayı gönder butonuna tıklayın.

Tam referans nerede

MailGraf public API sözleşmesini API referansında bulabilirsiniz. Webhook imza değerleri ve doğrulama örnekleri, Ayarlar > Webhook bölümünde her endpoint için gösterilir.