Ustvarite lastne integracije z webhooki

Pravilo »Pošlji v webhook« avtomatizira pošiljanje novih objav iz virov RSS na določeno končno točko webhooka, takoj ko so objave na voljo. Pošiljane objave lahko natančneje določite tudi s ključnimi besedami za filtriranje. Ko nova objava ustreza vašim merilom, jo Feeder pošlje na končno točko webhooka kot zahtevo POST v obliki JSON.

Oblika podatkov JSON

Vsaka zahteva POST, poslana na vaš webhook, vsebuje dva glavna elementa: post in feed.

Vsebuje tudi metapodatke za prepoznavanje sporočila webhooka. Polje version določa različico API-ja Feeder webhook, ki je uporabljena. Različica je vedno 2023-06-26 in bo posodobljena, če pride do nezdružljivih sprememb.

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

Element post vsebuje podatke o posamezni objavi:

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

Opomba: vrednost published bo null, če vir RSS ne vsebuje veljavnega datuma objave.

Element feed vsebuje podatke o viru, iz katerega izvira objava:

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

V prihodnje bomo morda te objekte dopolnili. Če vam kaj manjka, nam sporočite.

Logika ponovnih poskusov

Če zahteva ne uspe, jo Feeder samodejno poskusi poslati znova. Če zahteva POST ne prejme kode HTTP med 200 in 399, jo bomo poskusili znova poslati po spodnjem urniku, navedenem v sekundah:

• 1. poskus: po 5 sekundah
• 2. poskus: po 30 sekundah
• 3. poskus: po 60 sekundah
• 4. poskus: po 5 minutah
• 5. poskus: po 10 minutah
• 6. poskus: po 30 minutah
• 7. poskus: po 30 minutah
• 8. poskus: po 30 minutah

Upoštevajte, da se mehanizem ponovnih poskusov sproži samo ob dejanskih dogodkih objave in ne velja za testna obvestila. Časi se lahko tudi spremenijo.

Odpravljanje napak

Če pride do napak, jih najdete v dnevniku izvajanja dejanj. Odprite pravilo, ki ne deluje, in izberite »Odpri dnevnik napak«.

Tam boste našli več podrobnosti o webhookih, pri katerih je prišlo do napake.

Nastavitev webhooka

Webhook nastavite tako:

1. Odprite stran Pravila.
2. Ustvarite novo pravilo.
3. Vnesite ime ter izberite vire in merila.
4. V razdelku »Kaj naj se zgodi?« izberite »Pošlji v webhook«.
5. V predvideno besedilno polje vnesite URL webhooka.
6. Če želite preveriti, ali je vse pravilno nastavljeno, lahko z gumbom »Pošlji testno sporočilo« sprožite testno obvestilo na svoji končni točki. Upoštevajte, da gre le za preizkus in da se ob napaki ne sproži logika ponovnih poskusov. Za pošiljanje testne objave mora biti v vašem računu vsaj en vir z dodanimi objavami.

Varnost: preverjanje podpisov webhooka

Če želite zagotoviti, da zahteve webhooka res prihajajo od Feederja in niso bile spremenjene, lahko preverite skrivni ključ webhooka, ki se ustvari za vsak webhook. Vsaka zahteva webhooka vsebuje glavo X-Feeder-Signature s podpisom HMAC-SHA256 telesa zahteve.

Kako deluje

1. V nastavitvah pravila vklopite možnost »Napredno«. V polju »Skrivni ključ webhooka« se prikaže niz.
2. Ko Feeder pošlje webhook na vašo končno točko, z vašim skrivnim ključem kot ključem izračuna zgoščeno vrednost HMAC-SHA256 telesa zahteve JSON.
3. Dobljeni podpis se pošlje v glavi X-Feeder-Signature s predpono sha256=. Na primer:

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

4. Na strežniku znova izračunajte isto zgoščeno vrednost HMAC-SHA256 z neobdelanim telesom zahteve in svojo kopijo skrivnega ključa, nato pa jo primerjajte z vrednostjo v glavi.

Zakaj to uporabiti?

• Pristnost: potrdi, da je zahtevo poslal Feeder in ne tretja oseba.
• Celovitost: zagotavlja, da se vsebina med prenosom ni spremenila.

Preverjanje podpisa

Za preverjanje:

1. Neobdelano telo zahteve preberite kot niz, ne da bi ga prej razčlenili.
2. Izračunajte HMAC-SHA256 tega niza s svojim skrivnim ključem.
3. Izračunani podpis primerjajte z vrednostjo v glavi X-Feeder-Signature z uporabo primerjave, varne pred časovnimi napadi.

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

Pomembno: Za preverjanje podpisa morate uporabiti neobdelano telo zahteve. Če ogrodje pred izračunom HMAC razčleni telo JSON, se lahko znova serializirani niz razlikuje od izvirnika in podpis se ne bo ujemal. V Expressu na poti webhooka uporabite express.raw({ type: "application/json" }), kot je prikazano zgoraj.

Še kaj?

Imate vprašanja? Pišite nam na support@feeder.co.