Izrada vlastitih integracija pomoću webhookova

Pravilo „Objavi na Webhook” omogućuje automatizaciju slanja novih objava iz RSS izvora na zadanu krajnju točku webhooka čim postanu dostupne. Možete i preciznije odrediti koje se objave šalju tako da postavite ključne riječi prema kojima će se filtrirati. Kada nova objava odgovara vašim kriterijima, šalje se na krajnju točku webhooka u obliku POST zahtjeva s JSON podacima.

Format JSON podataka

Svaki POST zahtjev poslan na webhook sadržavat će dva glavna elementa: post i feed.

Sadrži i metapodatke za prepoznavanje poruke webhooka. Polje version označava verziju Feederova API-ja za webhookove koja se šalje. Verzija je fiksna i iznosi 2023-06-26, a ažurirat će se ako dođe do nekompatibilnih promjena.

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

Element post sadrži podatke o pojedinoj 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)
}

Napomena: vrijednost published bit će null ako RSS izvor nije naveo valjan datum objave.

Element feed sadrži podatke o izvoru iz kojeg potječe 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"
}

U budućnosti bismo mogli dodati još podataka u te objekte. Javite nam ako vam nešto nedostaje.

Ponovni pokušaji

Ako zahtjev ne uspije, Feeder će ga automatski ponovno pokušati poslati. Ako POST zahtjev ne primi HTTP odgovor s kodom od 200 do 399, pokušat ćemo ga ponovno poslati prema rasporedu u sekundama:

• 1. pokušaj ponovnog slanja: nakon 5 sekundi
• 2. pokušaj ponovnog slanja: nakon 30 sekundi
• 3. pokušaj ponovnog slanja: nakon 60 sekundi
• 4. pokušaj ponovnog slanja: nakon 5 minuta
• 5. pokušaj ponovnog slanja: nakon 10 minuta
• 6. pokušaj ponovnog slanja: nakon 30 minuta
• 7. pokušaj ponovnog slanja: nakon 30 minuta
• 8. pokušaj ponovnog slanja: nakon 30 minuta

Imajte na umu da se ponovni pokušaji pokreću samo za stvarne događaje objava i ne odnose se na testne obavijesti. Vremenski razmaci također se mogu promijeniti.

Otklanjanje poteškoća

Ako dođe do pogrešaka, možete ih pronaći u zapisniku izvršavanja radnje. Otvorite pravilo koje ne radi i pritisnite „Otvori zapisnik pogrešaka”.

Ondje ćete pronaći dodatne pojedinosti o neuspjelim webhookovima.

Postavljanje webhooka

Za postavljanje webhooka:

1. Otvorite stranicu Pravila.
2. Izradite novo pravilo.
3. Unesite naziv, odaberite izvore i postavite kriterije.
4. U odjeljku „Što bi trebalo učiniti?” odaberite „Objavi na Webhook”.
5. U predviđeno tekstno polje unesite URL webhooka.
6. Da biste provjerili je li sve ispravno postavljeno, možete pritisnuti gumb „Pošalji testnu poruku” i poslati testnu obavijest na svoju krajnju točku. Imajte na umu da je riječ samo o testu i da se, ako ne uspije, neće pokrenuti ponovni pokušaji slanja. Osim toga, da biste poslali testnu objavu, na računu morate imati barem jedan izvor s objavama.

Sigurnost: provjera potpisa webhooka

Da biste provjerili dolaze li zahtjevi webhooka zaista od Feedera i jesu li mijenjani, možete provjeriti tajnu vrijednost generiranu za svaki webhook. Svaki zahtjev webhooka sadržavat će zaglavlje X-Feeder-Signature s potpisom tijela zahtjeva izračunatim algoritmom HMAC-SHA256.

Kako funkcionira

1. U postavkama pravila uključite opciju „Napredno”. U polju „Tajna webhooka” prikazat će se niz znakova.
2. Kada Feeder pošalje webhook na vašu krajnju točku, izračunava sažetak HMAC-SHA256 tijela JSON zahtjeva, koristeći vašu tajnu vrijednost kao ključ.
3. Dobiveni se potpis šalje u zaglavlju X-Feeder-Signature s prefiksom sha256=. Na primjer:

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

4. Na svojem poslužitelju ponovno izračunajte isti sažetak HMAC-SHA256 koristeći sirovo tijelo zahtjeva i svoju kopiju tajne vrijednosti, a zatim ga usporedite s vrijednošću u zaglavlju.

Zašto to koristiti?

• Autentičnost: potvrđuje da je zahtjev poslao Feeder, a ne treća strana.
• Cjelovitost: jamči da podaci nisu izmijenjeni tijekom prijenosa.

Provjera potpisa

Za provjeru:

1. Pročitajte sirovo tijelo zahtjeva kao niz znakova. Nemojte ga prvo raščlaniti.
2. Izračunajte HMAC-SHA256 tog niza koristeći svoju tajnu vrijednost.
3. Usporedite izračunati potpis s vrijednošću zaglavlja X-Feeder-Signature pomoću usporedbe otporne na napade analizom vremena kako biste spriječili napade na temelju vremena izvršavanja.

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

Važno: Za provjeru potpisa morate pristupiti sirovom tijelu zahtjeva. Ako vaš okvir za razvoj aplikacija raščlani JSON tijelo prije izračuna HMAC-a, ponovno serijalizirani niz može se razlikovati od izvornog, pa se potpis neće podudarati. U Expressu na ruti webhooka upotrijebite express.raw({ type: "application/json" }), kao što je prikazano iznad.

Imate još pitanja?

Pitanja? Pišite nam na support@feeder.co.