Kaip kurti integracijas naudojant „Webhook“

Taisyklė „Siųsti į Webhook“ leidžia automatiškai siųsti naujus RSS sklaidos kanalų įrašus į jūsų nurodytą „webhook“ galinį tašką vos tik jie pasirodo. Taip pat galite tiksliai pasirinkti, kuriuos įrašus siųsti, nustatydami filtravimo raktažodžius. Kai naujas įrašas atitinka jūsų kriterijus, jis siunčiamas į „webhook“ galinį tašką kaip JSON formato POST užklausa.

JSON duomenų struktūra

Kiekvienoje į „webhook“ siunčiamoje POST užklausoje yra du pagrindiniai elementai: post ir feed.

Joje taip pat yra metaduomenų, pagal kuriuos galima identifikuoti „webhook“ pranešimą. Lauke version nurodoma, kuri Feeder „webhook“ API versija naudojama. Versija yra nekintama, 2023-06-26, ir bus atnaujinta, jei bus atlikta nesuderinamų pakeitimų.

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

Elemente post pateikiama informacija apie konkretų įrašą:

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

Pastaba: published reikšmė bus null, jei RSS sklaidos kanale nebuvo nurodyta galiojanti paskelbimo data.

Elemente feed pateikiama informacija apie sklaidos kanalą, iš kurio gautas įrašas:

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

Ateityje šiuos objektus galime papildyti. Jei jums ko nors trūksta, praneškite mums.

Pakartotiniai bandymai

Jei užklausa nepavyksta, Feeder automatiškai bando ją siųsti dar kartą. Jei POST užklausa negauna HTTP atsakymo kodo nuo 200 iki 399, ją bandysime išsiųsti pagal nurodytą tvarkaraštį. Laikas nurodytas sekundėmis:

• 1 bandymas: po 5 sekundžių
• 2 bandymas: po 30 sekundžių
• 3 bandymas: po 60 sekundžių
• 4 bandymas: po 5 minučių
• 5 bandymas: po 10 minučių
• 6 bandymas: po 30 minučių
• 7 bandymas: po 30 minučių
• 8 bandymas: po 30 minučių

Atkreipkite dėmesį, kad pakartotiniai bandymai vykdomi tik įvykus tikram įrašo įvykiui, o bandomiesiems pranešimams ši funkcija netaikoma. Laiko intervalai taip pat gali keistis.

Klaidų paieška

Jei įvyksta klaidų, jas rasite veiksmų vykdymo žurnale. Tiesiog atidarykite neveikiančią taisyklę ir spustelėkite „Atidaryti klaidų žurnalą“.

Ten rasite daugiau informacijos apie nepavykusius „webhook“ siuntimus.

„Webhook“ nustatymas

Norėdami nustatyti „webhook“:

1. Atidarykite puslapį Taisyklės.
2. Sukurkite naują taisyklę.
3. Nurodykite pavadinimą, sklaidos kanalus ir kriterijus.
4. Skiltyje „Kas turėtų įvykti?“ pasirinkite „Siųsti į Webhook“.
5. Įveskite „webhook“ URL į tam skirtą teksto lauką.
6. Norėdami įsitikinti, kad viskas nustatyta teisingai, spustelėkite mygtuką „Išbandykite pranešimą“ ir išsiųskite bandomąjį pranešimą į savo galinį tašką. Atkreipkite dėmesį, kad tai tik bandymas, todėl jam nepavykus pakartotinių bandymų mechanizmas nebus paleistas. Be to, norint išsiųsti bandomąjį įrašą, paskyroje turi būti bent vienas sklaidos kanalas su įrašais.

Saugumas: „webhook“ parašų patvirtinimas

Norėdami įsitikinti, kad gaunamos „webhook“ užklausos iš tikrųjų siunčiamos Feeder ir nebuvo pakeistos, galite patikrinti kiekvienam „webhook“ sugeneruotą slaptąjį raktą. Kiekvienoje „webhook“ užklausoje bus antraštė X-Feeder-Signature su užklausos turinio HMAC-SHA256 parašu.

Kaip tai veikia

1. Taisyklės nustatymuose įjunkite parinktį „Išplėstinis“. Lauke „Webhook Secret“ matysite eilutę.
2. Siųsdamas „webhook“ į jūsų galinį tašką, Feeder apskaičiuoja JSON užklausos turinio HMAC-SHA256 maišą, naudodamas jūsų slaptąjį raktą kaip raktą.
3. Gautas parašas siunčiamas antraštėje X-Feeder-Signature su priešdėliu sha256=. Pavyzdžiui:

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

4. Savo serveryje iš naujo apskaičiuokite tą pačią HMAC-SHA256 maišą, naudodami neapdorotą užklausos turinį ir savo slaptojo rakto kopiją, tada palyginkite ją su antraštėje esančia reikšme.

Kodėl verta tai naudoti?

• Autentiškumas: patvirtinama, kad užklausą išsiuntė Feeder, o ne trečioji šalis.
• Vientisumas: užtikrinama, kad perduodami duomenys nebuvo pakeisti.

Parašo tikrinimas

Norėdami patikrinti parašą:

1. Nuskaitykite neapdorotą užklausos turinį kaip eilutę, prieš tai jo neanalizuodami.
2. Apskaičiuokite šios eilutės HMAC-SHA256 naudodami savo slaptąjį raktą.
3. Palyginkite apskaičiuotą parašą su antraštės X-Feeder-Signature reikšme, naudodami laikui atsparų palyginimą, kad išvengtumėte laiko analizės atakų.

Pavyzdys: 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);
  }
);

Svarbu: norėdami patikrinti parašą, turite pasiekti neapdorotą užklausos turinį. Jei jūsų karkasas prieš apskaičiuojant HMAC išanalizuoja JSON turinį, iš naujo serializuota eilutė gali skirtis nuo pradinės, todėl parašai nesutaps. „Express“ sistemoje naudokite express.raw({ type: "application/json" }) „webhook“ maršrute, kaip parodyta pirmiau.

Dar turite klausimų?

Turite klausimų? Parašykite mums el. paštu support@feeder.co.