Webhook En İyi Uygulamaları

Üreticiler İçin (Webhook Gönderme)

Her Payload'ı İmzalayın

Giden her webhook, başlıklarda bir HMAC-SHA256 imzası içermelidir. Bu, tüketicilerin payload'ın değiştirilmediğini doğrulamasını sağlar. HookSniff bunu otomatik yapar — her teslimat, uç noktanın imza gizli anahtarıyla imzalanır.

webhook-signature: v1,base64(hmac_sha256(secret, "{id}.{timestamp}.{body}"))
webhook-timestamp: 1705312200
webhook-id: msg_abc123

Asla payload'ın yeniden serileştirilmiş bir versiyonunu imzalamayın. Bayt farkları doğrulamayı bozar. Ham istek gövdesini kullanın.

İdempotans Anahtarı Ekleyin

Tüketicilerin tekrarsızlaştırabilmesi için her olaya benzersiz bir tanımlayıcı ekleyin:

curl -X POST https://hooksniff-api-1046140057667.europe-west1.run.app/v1/webhooks \
  -H "Authorization: Bearer hr_live_YOUR_KEY" \
  -H "Idempotency-Key: order-12345-created" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_id": "ep_abc123",
    "event": "order.created",
    "data": {
      "order_id": "12345",
      "total": 99.99,
      "currency": "USD"
    }
  }'

Rastgele UUID'ler yerine iş mantığı tanımlayıcıları kullanın (ör. siparis-{id}-olusturuldu). Bu, aynı işlemin her zaman aynı anahtarı üretmesini sağlar.

Payload'ları Stabilite İçin Tasarlayın

Payload'ları kendi kendine yeterli tutun. Tüketicileri size API çağrısı yapmaya zorlamak yerine ihtiyaç duydukları tüm veriyi ekleyin.

{
  "event": "order.shipped",
  "data": {
    "order_id": "ord_123",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "ups",
    "shipped_at": "2026-01-15T14:00:00Z"
  }
}

{
  "event": "order.shipped",
  "data": {
    "order_id": "ord_123"
  }
}

Tutarlı Olay Türü Adlandırması Kullanın

Nokta ayırıcılarıyla resource.action formatını kullanın:

• order.created, order.updated, order.cancelled
• payment.succeeded, payment.failed
• user.created, user.updated

Spesifik olun: invoice.payment_failed, invoice.error'dan daha iyidir.

Tüketiciler İçin (Webhook Alma)

Önce İmzaları Doğrulayın

Herhangi bir webhook'u işlemeden önce HMAC imzasını doğrulayın. Eksik veya geçersiz imzalı istekleri hemen reddedin.

from hooksniff import Webhook

wh = Webhook("whsec_your_secret")

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    try:
        payload = wh.verify(
            request.data,
            {
                "webhook-id": request.headers["webhook-id"],
                "webhook-timestamp": request.headers["webhook-timestamp"],
                "webhook-signature": request.headers["webhook-signature"],
            },
        )
        # ✅ Valid — process event
        return "", 200
    except Exception:
        return "Invalid signature", 401

Zamanlama saldırılarını önlemek için sabit zamanlı karşılaştırma (hmac.compare_digest) kullanın.

Hızlı Yanıt Verin, Sonra İşleyin

5 saniye içinde bir 200 OK döndürün. Gerçek işlemeyi asenkron yapın:

import { Webhook } from 'hooksniff';
const wh = new Webhook('whsec_your_secret');

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  // 1. Verify signature (fast)
  try {
    const payload = wh.verify(req.body, {
      'webhook-id': req.headers['webhook-id'],
      'webhook-timestamp': req.headers['webhook-timestamp'],
      'webhook-signature': req.headers['webhook-signature'],
    });
  } catch (err) {
    return res.status(401).send('Invalid signature');
  }

  // 2. Respond immediately
  res.status(200).json({ received: true });

  // 3. Process asynchronously
  processWebhookAsync(JSON.parse(req.body));
});

Uç noktanız çok uzun sürerse, HookSniff zaman aşımına uğrayıp tekrar deneyebilir, bu da tekrarlamaya yol açar.

Tekrarları Yönetin

Webhook'lar birden fazla teslim edilebilir. İşlenmiş teslimat ID'lerini takip edin:

CREATE TABLE processed_webhooks (
    delivery_id TEXT PRIMARY KEY,
    processed_at TIMESTAMPTZ DEFAULT NOW()
);

-- Before processing, check if already processed
SELECT 1 FROM processed_webhooks WHERE delivery_id = $1;

Yalnızca HTTPS Kullanın

Webhook uç noktalarını her zaman HTTPS üzerinden sunun. HookSniff varsayılan olarak yalnızca HTTPS uç noktalarına teslimat yapar. HTTP uç noktaları açıkça izin verilmedikçe reddedilir.

İzleme ve Uyarı

Sorunları erken yakalamak için bu metrikleri takip edin:

Bu eşikler aşıldığında bildirim almak için HookSniff'in yerleşik alarmlarını kullanın.