Vlastní integrace pomocí webhooků

Pravidlo „Odeslat na Webhook“ automatizuje odesílání nových příspěvků z RSS kanálů na zadaný endpoint webhooku, jakmile jsou dostupné. Odesílané příspěvky můžete upřesnit také nastavením klíčových slov, podle kterých se budou filtrovat. Když nový příspěvek splní vaše kritéria, odešle se na endpoint webhooku jako požadavek POST ve formátu JSON.

Formát dat JSON

Každý požadavek POST odeslaný na webhook obsahuje dvě hlavní části: post a feed.

Obsahuje také metadata, která identifikují zprávu webhooku. Pole version uvádí verzi rozhraní API webhooků Feederu, která se odesílá. Verze zůstává konstantní, tedy 2023-06-26, a změní se pouze v případě nekompatibilních změn.

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

Část post obsahuje informace o konkrétním příspěvku:

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

Poznámka: Hodnota published bude null, pokud RSS kanál neobsahuje platné datum publikování.

Část feed obsahuje informace o kanálu, ze kterého příspěvek pochází:

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

Tyto objekty můžeme v budoucnu rozšířit. Pokud vám v nich něco chybí, dejte nám vědět.

Opakování pokusů

Pokud požadavek selže, Feeder jej automaticky zkusí odeslat znovu. Jestliže požadavek POST neobdrží HTTP stavový kód v rozmezí 200 až 399, pokusíme se jej odeslat znovu podle následujícího časového plánu v sekundách:

• 1. opakování: po 5 sekundách
• 2. opakování: po 30 sekundách
• 3. opakování: po 60 sekundách
• 4. opakování: po 5 minutách
• 5. opakování: po 10 minutách
• 6. opakování: po 30 minutách
• 7. opakování: po 30 minutách
• 8. opakování: po 30 minutách

Upozorňujeme, že opakování pokusů se spouští pouze při skutečném přidání příspěvku, netýká se testovacích oznámení. Časové intervaly se také mohou změnit.

Řešení problémů

Pokud dojde k chybě, najdete ji v protokolu spuštění akce. Otevřete nefungující pravidlo a klikněte na „Otevřít protokol chyb“.

Zobrazí se další podrobnosti o neúspěšných webhoocích.

Nastavení webhooku

Webhook nastavíte takto:

1. Přejděte na stránku Pravidla.
2. Vytvořte nové pravidlo.
3. Zadejte jeho název, kanály a kritéria.
4. V části „Co by se mělo stát?“ vyberte „Odeslat na Webhook“.
5. Do příslušného textového pole zadejte adresu URL webhooku.
6. Ověřte správnost nastavení tlačítkem „Odeslat testovací zprávu“. Tím odešlete na svůj endpoint testovací oznámení. Jde pouze o test, při jeho selhání se nespustí opakování pokusů. Aby se testovací příspěvek odeslal, musíte mít v účtu alespoň jeden kanál s přidanými příspěvky.

Zabezpečení: ověřování podpisů webhooků

Chcete-li ověřit, že příchozí požadavky webhooku skutečně pocházejí od Feederu a nebyly pozměněny, můžete ověřit tajný klíč vygenerovaný pro každý webhook. Každý požadavek webhooku obsahuje hlavičku X-Feeder-Signature s podpisem těla požadavku vytvořeným algoritmem HMAC-SHA256.

Jak to funguje

1. V nastavení pravidla zapněte možnost „Pokročilé“. V poli „Tajný klíč webhooku“ se zobrazí řetězec.
2. Když Feeder odešle webhook na váš endpoint, vypočítá hash HMAC-SHA256 těla požadavku ve formátu JSON. Jako klíč použije váš tajný klíč.
3. Výsledný podpis se odešle v hlavičce X-Feeder-Signature s předponou sha256=. Například:

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

4. Na serveru znovu vypočítáte stejný hash HMAC-SHA256 z původního těla požadavku a své kopie tajného klíče a výsledek porovnáte s hodnotou v hlavičce.

Proč to používat?

• Pravost: Potvrzuje, že požadavek odeslal Feeder, nikoli třetí strana.
• Integrita: Zaručuje, že datový obsah nebyl během přenosu změněn.

Ověření podpisu

Postup ověření:

1. Načtěte původní tělo požadavku jako řetězec, předtím jej neparsujte.
2. Pomocí svého tajného klíče vypočítejte HMAC-SHA256 tohoto řetězce.
3. Vypočítaný podpis porovnejte s hodnotou hlavičky X-Feeder-Signature pomocí porovnání odolného vůči časovým útokům.

Příklad: 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);
  }
);

Důležité: Při ověřování podpisu musíte pracovat s původním tělem požadavku. Pokud váš framework před výpočtem HMAC parsuje tělo JSON, převedený řetězec se může lišit od originálu a podpis nebude odpovídat. V Expressu použijte na trase webhooku express.raw({ type: "application/json" }), jak je uvedeno výše.

Ještě něco?

Máte otázky? Napište nám na support@feeder.co.