Webhook’larla kendi entegrasyonlarınızı oluşturun

“Webhook'a gönder” kuralı, yeni RSS akışı gönderilerini kullanılabilir olur olmaz belirttiğiniz webhook uç noktasına otomatik olarak göndermenizi sağlar. Filtreleme için anahtar kelimeler belirleyerek hangi gönderilerin iletileceğini de özelleştirebilirsiniz. Yeni bir gönderi ölçütlerinize uyduğunda, webhook uç noktanıza JSON biçiminde bir POST isteği gönderilir.

JSON içerik biçimi

Webhook'unuza gönderilen her POST isteği iki ana öğe içerir: post ve feed.

İstek, webhook mesajını tanımlamak için meta veri öğeleri de içerir. version alanı, Feeder webhook API'sinin hangi sürümünün gönderildiğini belirtir. Sürüm sabit olarak 2023-06-26 değerini taşır ve geriye dönük uyumluluğu bozan değişiklikler yapılırsa güncellenir.

{
  "version": "2023-06-26",
  "message_id": "a unique UUID for this message, will be constant during retries",
  "feed": { ... },
  "post": { ... }
}

post öğesi, gönderiyle ilgili bilgileri içerir:

{
  "id": "The unique identifier of the post",
  "title": "The title of the post",
  "url": "The URL where the post can be accessed",
  "published": "The date and time when the post was published",
  "content": "The content of the post",
  "audio_url": "link to mp3 attached to post (if present)",
  "image_url": "link to image attached to post (if present)
}

Not: RSS akışında geçerli bir yayın tarihi belirtilmemişse published değeri null olur.

feed öğesi, gönderinin geldiği akışla ilgili bilgileri sağlar:

{
  "id": "The unique identifier of the feed",
  "source_url": "The URL of the source, for example RSS/Atom feed URL",
  "public_url": "The source's self identified public URL",
  "title": "The title of the feed",
  "favicon": "The URL of the feed's favicon"
}

Bu nesnelere gelecekte yeni alanlar ekleyebiliriz. Eksik olduğunu düşündüğünüz bir şey varsa lütfen bize bildirin.

Yeniden deneme mantığı

Bir istek başarısız olursa Feeder isteği otomatik olarak yeniden dener. POST isteğine 200 ile 399 arasında bir HTTP yanıt kodu dönmezse, isteği saniye cinsinden belirtilen takvime göre yeniden göndermeyi deneriz:

• 1. yeniden deneme: 5 saniye sonra
• 2. yeniden deneme: 30 saniye sonra
• 3. yeniden deneme: 60 saniye sonra
• 4. yeniden deneme: 5 dakika sonra
• 5. yeniden deneme: 10 dakika sonra
• 6. yeniden deneme: 30 dakika sonra
• 7. yeniden deneme: 30 dakika sonra
• 8. yeniden deneme: 30 dakika sonra

Bu yeniden deneme mekanizmasının yalnızca gerçek gönderi olaylarında devreye girdiğini, test bildirimlerinde uygulanmadığını unutmayın. Zamanlamalar da değişebilir.

Hata ayıklama

Hata oluşursa işlem çalıştırma günlüğünde bulabilirsiniz. Çalışmayan kuralı açıp “Hata günlüğünü aç” seçeneğine tıklamanız yeterlidir.

Burada başarısız olan webhook'larla ilgili daha fazla ayrıntı görebilirsiniz.

Webhook'unuzu ayarlama

Webhook'unuzu ayarlamak için:

1. Kurallar sayfasına gidin.
2. Yeni bir kural oluşturun.
3. Adı, akışları ve ölçütleri ekleyin.
4. “Ne olmalı?” bölümünde “Webhook'a gönder” seçeneğini belirleyin.
5. Sağlanan metin alanına webhook URL'nizi girin.
6. Her şeyin doğru ayarlandığından emin olmak için uç noktanıza bir test bildirimi göndermek üzere “Test mesajı gönder” düğmesini kullanabilirsiniz. Bunun yalnızca bir test olduğunu ve başarısız olması durumunda yeniden deneme mantığının devreye girmeyeceğini unutmayın. Test gönderisinin iletilebilmesi için hesabınıza gönderiler eklenmiş en az bir akış eklemiş olmanız gerekir.

Güvenlik: Webhook imzalarını doğrulama

Gelen webhook isteklerinin gerçekten Feeder'dan geldiğinden ve üzerinde değişiklik yapılmadığından emin olmak için her webhook için oluşturulan webhook gizli anahtarını doğrulayabilirsiniz. Her webhook isteğinde, istek gövdesinin HMAC-SHA256 imzasını içeren bir X-Feeder-Signature başlığı bulunur.

Nasıl çalışır?

1. Kural ayarlarınızda “Gelişmiş” seçeneğini etkinleştirin. “Webhook gizli anahtarı” alanında bir dize göreceksiniz.
2. Feeder uç noktanıza webhook gönderdiğinde, gizli anahtarınızı anahtar olarak kullanarak JSON istek gövdesinin HMAC-SHA256 özetini hesaplar.
3. Ortaya çıkan imza, başına sha256= eklenecek şekilde X-Feeder-Signature başlığında gönderilir. Örneğin:

   X-Feeder-Signature: sha256=a1b2c3d4e5f6...

4. Sunucunuzda aynı HMAC-SHA256 özetini ham istek gövdesini ve gizli anahtarınızın kopyasını kullanarak yeniden hesaplayın, ardından başlıktaki değerle karşılaştırın.

Neden kullanmalısınız?

• Kaynağın doğrulanması: İsteğin üçüncü bir tarafça değil Feeder tarafından gönderildiğini doğrular.
• Bütünlük: İçeriğin aktarım sırasında değiştirilmediğini garanti eder.

İmzayı doğrulama

Doğrulamak için:

1. Ham istek gövdesini bir dize olarak okuyun. Önce ayrıştırmayın.
2. Gizli anahtarınızı kullanarak bu dizenin HMAC-SHA256 özetini hesaplayın.
3. Zamanlama saldırılarını önlemek için hesapladığınız imzayı X-Feeder-Signature başlık değerine karşı zamanlama saldırılarına dayanıklı karşılaştırma kullanarak karşılaştırın.

Örnek: Node.js (Express)

const crypto = require("crypto");

const WEBHOOK_SECRET = process.env.FEEDER_WEBHOOK_SECRET;

function verifyFeederSignature(req, res, next) {
  const signature = req.headers["x-feeder-signature"];
  if (!signature) {
    return res.status(401).send("Missing signature");
  }

  const expectedSignature =
    "sha256=" +
    crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.body).digest("hex");

  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  next();
}

// Important: use express.raw() so req.body is the raw string, not parsed JSON
app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  verifyFeederSignature,
  (req, res) => {
    const payload = JSON.parse(req.body);
    // Handle the webhook payload
    console.log("Received verified webhook:", payload);
    res.sendStatus(200);
  }
);

Önemli: İmza doğrulaması için ham istek gövdesine erişmeniz gerekir. HMAC'i hesaplamadan önce çerçeveniz JSON gövdesini ayrıştırırsa, yeniden serileştirilmiş dize orijinalinden farklı olabilir ve imza eşleşmez. Yukarıda gösterildiği gibi Express'te webhook rotasında express.raw({ type: "application/json" }) kullanın.

Başka bir şey var mı?

Sorularınız mı var? support@feeder.co adresine e-posta gönderin.