İmza Doğrulama

Her webhook teslimi, isteğin MailLand'den geldiğini ve aktarım sırasında değiştirilmediğini doğrulayabilmeniz için bir şifreleme imzası içerir. Üretim ortamında her zaman imzaları doğrulayın.

İmzalama Nasıl ÇalışırBölüm bağlantısını kopyala

MailLand, her webhook verisini webhook'unuzun gizli anahtarını kullanarak HMAC-SHA256 ile imzalar. İmza X-MLND-Signature başlığına eklenir.

İmza biçimi:

X-MLND-Signature: t=1708171200,v1=b9f747ea899eafe911777060ca8f3c90828d37f1e16ee6e9ee98dacf8b316b67

İmzalanan veri:

{timestamp}.{raw_json_body}

İmza, zaman damgasının bir nokta ve ham JSON istek gövdesiyle birleştirilmesiyle hesaplanır.

Çalışılmış ÖrnekBölüm bağlantısını kopyala

Canlıya geçmeden önce uygulamanızı tam olarak bu değerlerle karşılaştırın. Aşağıdaki her şey gerçektir: imza, MailLand’in bu gizli anahtar, zaman damgası ve gövde için ürettiği imzadır.

İmzalanan dize: zaman damgası, bir nokta, sonra gövdenin aynısı:

1708171200.{"event":"message.delivered","event_id":"evt_a1b2c3d4e5f6"}

Bu dizenin gizli anahtarla üretilmiş HMAC-SHA256 değeri, küçük harfli onaltılık:

b9f747ea899eafe911777060ca8f3c90828d37f1e16ee6e9ee98dacf8b316b67

Bu teslimattaki başlık şöyle olurdu:

X-MLND-Signature: t=1708171200,v1=b9f747ea899eafe911777060ca8f3c90828d37f1e16ee6e9ee98dacf8b316b67

Tek satırda yeniden üretin:

printf '%s' '1708171200.{"event":"message.delivered","event_id":"evt_a1b2c3d4e5f6"}' \
  | openssl dgst -sha256 -hmac 'whsec_docs_example_secret_do_not_use'

Bu örneğin zaman damgası geçmişte kaldığı için gerçek bir doğrulayıcı onu tolerans kontrolünde reddeder. Önce zaman kontrolünü kapatıp HMAC’i test edin, sonra yeniden açın.

Gönderilen BaşlıklarBölüm bağlantısını kopyala

Her webhook teslimi şu başlıkları içerir:

Hangi olaya abone olduğunuza bağlı iki başlık daha vardır:

X-MLND-Message-Id şu anda message.* teslimatlarında gönderilmiyor. Bunun yerine olay yükündeki data.message_id alanını kullanın.

Doğrulama AdımlarıBölüm bağlantısını kopyala

signed_payload = timestamp + "." + raw_body

Kod ÖrnekleriBölüm bağlantısını kopyala

#!/usr/bin/env bash
# Compute and verify an HMAC-SHA256 webhook signature using openssl

SIGNATURE_HEADER="t=1708171200,v1=b9f747ea899eafe911777060ca8f3c90828d37f1e16ee6e9ee98dacf8b316b67"
RAW_BODY='{"event":"message.delivered","event_id":"evt_a1b2c3d4e5f6"}'
SECRET="whsec_docs_example_secret_do_not_use"
TOLERANCE=300

# Parse timestamp and signature from header
TIMESTAMP=$(echo "$SIGNATURE_HEADER" | grep -oP '(?<=t=)[^,]+')
RECEIVED_SIG=$(echo "$SIGNATURE_HEADER" | grep -oP '(?<=v1=).+')

# Check timestamp tolerance
NOW=$(date +%s)
DIFF=$(( NOW - TIMESTAMP ))
if [ "${DIFF#-}" -gt "$TOLERANCE" ]; then
  echo "Error: Timestamp outside tolerance window" >&2
  exit 1
fi

# Compute expected signature
SIGNED_PAYLOAD="${TIMESTAMP}.${RAW_BODY}"
EXPECTED=$(printf '%s' "$SIGNED_PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

# Compare signatures
if [ "$EXPECTED" = "$RECEIVED_SIG" ]; then
  echo "Signature valid"
else
  echo "Signature invalid" >&2
  exit 1
fi

Yeniden Oynatma Saldırısı ÖnlemeBölüm bağlantısını kopyala

İmza başlığındaki zaman damgası, yeniden oynatma saldırılarını önler. Bir saldırgan geçerli bir webhook teslimatını yakalayıp daha sonra yeniden gönderirse, zaman damgası kontrolü bunu reddeder.

MailLand'in varsayılan toleransı 5 dakika (300 saniye)'dir. Bunu doğrulama kodunuzda ayarlayabilirsiniz, ancak anlamlı yeniden oynatma saldırılarını önlemek için yeterince kısa tutun.

Ayrıca her olayın X-MLND-Event-Id başlığında benzersiz bir event_id değeri bulunur. Ek koruma için işlenmiş olay kimliklerini saklayın ve kopyaları reddedin.

Her Teslimat İmzalıdırBölüm bağlantısını kopyala

İmzasız bir teslimat yolu yoktur. Bir webhook'un kullanılabilir bir imzalama gizli anahtarı yoksa, MailLand veriyi X-MLND-Signature başlığı olmadan göndermek yerine teslimatı başarısız kılar ve bu hatayı kaydeder: bu yüzden eksik bir imza başlığı, doğrulayıcınızın hiçbir zaman göz ardı etmesi gereken bir şey değildir. Bu başlığı taşımayan her isteği reddedin.

Gizli Anahtarları Yeniden OluşturmaBölüm bağlantısını kopyala

Webhook gizli anahtarınızın ele geçirildiğinden şüpheleniyorsanız:

1. Yeni bir gizli anahtar almak için POST /v1/webhooks/{id}/regenerate-secret çağrısı yapın
2. Sunucunuzun doğrulama kodunu yeni gizli anahtarla güncelleyin
3. Eski gizli anahtar hemen geçersiz kılınır

Yaygın HatalarBölüm bağlantısını kopyala

• Doğrulamadan önce gövdeyi JSON olarak ayrıştırma: imza ham baytlar üzerinden hesaplanır, yeniden seri hale getirilmiş bir JSON nesnesi üzerinden değil. Önce doğrulayın, sonra ayrıştırın.
• Sabit zamanlı yerine dize karşılaştırması kullanma: normal dize karşılaştırması zamanlama saldırılarına karşı savunmasızdır.
• Zaman damgasını yok sayma: zaman damgası doğrulaması olmadan, yakalanan veriler süresiz olarak yeniden oynatılabilir.
• Gizli anahtarı sabit kodlama: ortam değişkenleri veya gizli anahtar yöneticisi kullanın.

Sonraki AdımlarBölüm bağlantısını kopyala

• Yeniden Deneme Mantığı: yeniden deneme davranışını ve hata yönetimini anlayın
• Olaylar: tam olay türü başvurusu
• Webhook'lara Genel Bakış: webhook'ları oluşturun ve yönetin