Ako vytvoriť vlastné integrácie pomocou webhookov

Pravidlo „Odoslať na Webhook“ automatizuje odosielanie nových príspevkov z RSS kanálov na určený koncový bod webhooku hneď po ich zverejnení. Pomocou kľúčových slov môžete nastaviť filtre a spresniť, ktoré príspevky sa majú odosielať. Keď nový príspevok spĺňa vaše kritériá, odošle sa na koncový bod webhooku ako požiadavka POST vo formáte JSON.

Formát údajov JSON

Každá požiadavka POST odoslaná na váš webhook obsahuje dva hlavné prvky: post a feed.

Obsahuje aj metadáta, pomocou ktorých možno identifikovať správu webhooku. Pole version určuje verziu rozhrania Feeder webhook API. Jeho hodnota je vždy 2023-06-26 a aktualizuje sa v prípade zmien, ktoré nie sú spätne kompatibilné.

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

Prvok post obsahuje informácie o konkrétnom príspevku:

{
  "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, ak RSS kanál neobsahuje platný dátum zverejnenia.

Prvok feed obsahuje informácie o kanáli, z ktorého príspevok pochádza:

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

Tieto objekty môžeme v budúcnosti rozšíriť. Ak vám niečo chýba, dajte nám vedieť.

Opakovanie pokusov

Ak požiadavka zlyhá, Feeder ju automaticky skúsi odoslať znova. Ak požiadavka POST nedostane HTTP stavový kód v rozsahu 200 až 399, pokúsime sa ju odoslať znova podľa tohto časového plánu, uvedeného v sekundách:

• 1. opakovanie: po 5 sekundách
• 2. opakovanie: po 30 sekundách
• 3. opakovanie: po 60 sekundách
• 4. opakovanie: po 5 minútach
• 5. opakovanie: po 10 minútach
• 6. opakovanie: po 30 minútach
• 7. opakovanie: po 30 minútach
• 8. opakovanie: po 30 minútach

Upozorňujeme, že tento mechanizmus opakovania sa spustí len pri skutočných udalostiach súvisiacich s príspevkami. Nevzťahuje sa na testovacie upozornenia. Časové intervaly sa môžu zmeniť.

Riešenie problémov

Ak sa vyskytnú chyby, nájdete ich v denníku spustení akcií. Otvorte pravidlo, ktoré nefunguje, a kliknite na „Otvoriť denník chýb“.

Zobrazia sa podrobnejšie informácie o neúspešných webhookoch.

Nastavenie webhooku

Webhook nastavíte takto:

1. Prejdite na stránku Pravidlá.
2. Vytvorte nové pravidlo.
3. Zadajte názov a vyberte kanály a kritériá.
4. V časti „Čo by sa malo stať?“ vyberte „Odoslať na Webhook“.
5. Do príslušného textového poľa zadajte URL adresu webhooku.
6. Správnosť nastavenia môžete overiť kliknutím na tlačidlo „Odoslať testovaciu správu“, ktoré odošle testovacie upozornenie na váš koncový bod. Upozorňujeme, že ide len o test. Ak zlyhá, nespustí sa opakovanie pokusov. Na odoslanie testovacieho príspevku musí byť vo vašom účte aspoň jeden kanál s pridanými príspevkami.

Zabezpečenie: overenie podpisov webhooku

Ak chcete overiť, že prichádzajúce požiadavky webhooku skutočne pochádzajú z Feederu a neboli pozmenené, môžete overiť tajný kľúč vygenerovaný pre každý webhook. Každá požiadavka webhooku obsahuje hlavičku X-Feeder-Signature s podpisom tela požiadavky vytvoreným algoritmom HMAC-SHA256.

Ako to funguje

1. V nastaveniach pravidla zapnite možnosť „Pokročilé“. V poli „Tajný kľúč webhooku“ sa zobrazí reťazec.
2. Keď Feeder odošle webhook na váš koncový bod, pomocou vášho tajného kľúča vypočíta hash tela požiadavky JSON algoritmom HMAC-SHA256.
3. Výsledný podpis sa odošle v hlavičke X-Feeder-Signature s predponou sha256=. Napríklad:

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

4. Na serveri vypočítajte rovnaký hash HMAC-SHA256 z nespracovaného tela požiadavky pomocou svojej kópie tajného kľúča a potom ho porovnajte s hodnotou v hlavičke.

Prečo to používať?

• Pravosť: Potvrdzuje, že požiadavku odoslal Feeder, nie tretia strana.
• Integrita: Zaručuje, že údaje neboli počas prenosu pozmenené.

Overenie podpisu

Postup overenia:

1. Načítajte nespracované telo požiadavky ako reťazec, najprv ho neparsujte.
2. Pomocou svojho tajného kľúča vypočítajte HMAC-SHA256 tohto reťazca.
3. Vypočítaný podpis porovnajte s hodnotou hlavičky X-Feeder-Signature pomocou porovnania odolného voči časovým útokom.

Prí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é: Na overenie podpisu musíte pracovať s nespracovaným telom požiadavky. Ak váš framework pred výpočtom HMAC parsuje telo JSON, znovu vytvorený reťazec sa môže líšiť od pôvodného a podpis nebude súhlasiť. V Express použite na trase webhooku express.raw({ type: "application/json" }), ako je uvedené vyššie.

Ešte niečo?

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