Saját integrációk készítése webhookokkal

A „Üzenet küldése a Webhook-ra” szabállyal automatizálhatod az új RSS-bejegyzések elküldését a megadott webhook-végpontra, amint elérhetővé válnak. Kulcsszavak megadásával azt is beállíthatod, hogy mely bejegyzéseket küldje el a rendszer. Ha egy új bejegyzés megfelel a feltételeknek, JSON-formátumú POST-kérésként továbbítjuk a webhook-végpontra.

JSON-adatformátum

A webhookra küldött POST-kérés két fő elemet tartalmaz: a post és a feed objektumot.

A webhooküzenet azonosításához metaadatok is tartoznak hozzá. A version mező jelzi, hogy a Feeder webhook API-jának melyik verzióját használjuk. Ennek értéke állandóan 2023-06-26, és csak akkor változik, ha nem visszafelé kompatibilis módosítás történik.

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

A post elem az adott bejegyzés adatait tartalmazza:

{
  "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)
}

Megjegyzés: a published értéke null, ha az RSS-hírcsatorna nem adott meg érvényes közzétételi dátumot.

A feed elem annak a hírcsatornának az adatait tartalmazza, amelyből a bejegyzés származik:

{
  "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"
}

A jövőben bővíthetjük ezeket az objektumokat. Ha hiányol valamit, kérjük, jelezze nekünk.

Újrapróbálkozások

Ha egy kérés sikertelen, a Feeder automatikusan újrapróbálja. Ha a POST-kérésre nem érkezik 200 és 399 közötti HTTP-válaszkód, az alábbi, másodpercben megadott ütemezés szerint megpróbáljuk újraküldeni:

• 1. újrapróbálkozás: 5 másodperc múlva
• 2. újrapróbálkozás: 30 másodperc múlva
• 3. újrapróbálkozás: 60 másodperc múlva
• 4. újrapróbálkozás: 5 perc múlva
• 5. újrapróbálkozás: 10 perc múlva
• 6. újrapróbálkozás: 30 perc múlva
• 7. újrapróbálkozás: 30 perc múlva
• 8. újrapróbálkozás: 30 perc múlva

Fontos, hogy az újrapróbálkozás csak valódi bejegyzéseknél indul el, tesztértesítéseknél nem. Az időzítés változhat.

Hibakeresés

Ha hiba történik, a műveletek futási naplójában találod meg. Nyisd meg a nem működő szabályt, majd válaszd a „Hibanapló megnyitása” lehetőséget.

Itt további részleteket találsz a sikertelen webhookokról.

A webhook beállítása

A webhook beállítása:

1. Nyisd meg a Szabályok oldalt.
2. Hozz létre egy új szabályt.
3. Add meg a nevét, a hírcsatornákat és a feltételeket.
4. A „Mi történjen?” résznél válaszd az „Üzenet küldése a Webhook-ra” lehetőséget.
5. Írd be a webhook URL-jét a megadott szövegmezőbe.
6. A beállítás ellenőrzéséhez a „Teszt üzenet küldése” gombbal tesztértesítést küldhetsz a végpontra. Ez csak teszt, sikertelenség esetén nem indul el az újrapróbálkozás. A tesztüzenet elküldéséhez legalább egy olyan hírcsatornára van szükség a fiókodban, amelyhez már érkeztek bejegyzések.

Biztonság: a webhook-aláírások ellenőrzése

Annak ellenőrzéséhez, hogy a bejövő webhookkérések valóban a Feedertől érkeznek-e, és nem módosították-e őket, ellenőrizheted az egyes webhookokhoz létrehozott titkos kulcsot. Minden webhookkérés tartalmaz egy X-Feeder-Signature fejlécet, amely a kérés törzsére számított HMAC-SHA256-aláírást tartalmazza.

Így működik

1. A szabály beállításainál kapcsold be a „Haladó” lehetőséget. A „Webhook titkos kulcsa” mezőben megjelenik egy karakterlánc.
2. Amikor a Feeder webhookot küld a végpontodra, a JSON-kérés törzséből HMAC-SHA256-kivonatot számít, a titkos kulcsot használva kulcsként.
3. Az így kapott aláírás a X-Feeder-Signature fejlécben érkezik, sha256= előtaggal. Például:

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

4. A szervereden számítsd ki újra ugyanazt a HMAC-SHA256-kivonatot a nyers kérés törzséből és a titkos kulcs saját példányából, majd hasonlítsd össze a fejlécben kapott értékkel.

Miért érdemes ezt használni?

• Eredetiség: megerősíti, hogy a kérést a Feeder küldte, nem pedig egy harmadik fél.
• Sértetlenség: biztosítja, hogy az adatok nem módosultak továbbítás közben.

Az aláírás ellenőrzése

Az ellenőrzés lépései:

1. Olvasd be a nyers kérés törzsét karakterláncként, és előtte ne dolgozd fel.
2. Számítsd ki a karakterlánc HMAC-SHA256-értékét a titkos kulcsoddal.
3. Hasonlítsd össze a kiszámított aláírást az X-Feeder-Signature fejléc értékével időzítésbiztos összehasonlítással, hogy megelőzd az időzítéses támadásokat.

Példa: 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);
  }
);

Fontos: Az aláírás ellenőrzéséhez a kérés törzsét nyers formában kell elérned. Ha a keretrendszered már a HMAC kiszámítása előtt feldolgozza a JSON-törzset, az újraszerializált karakterlánc eltérhet az eredetitől, és az aláírás nem fog egyezni. Expressben használd az express.raw({ type: "application/json" }) beállítást a webhook útvonalán, ahogy fent látható.

Van még kérdésed?

Kérdés esetén írj nekünk a support@feeder.co címre.