Kako da napravite sopstvene integracije pomoću vebhukova

Pravilo „Objaviti na Webhook“ omogućava vam da automatizujete slanje novih objava iz RSS izvora na izabranu krajnju tačku vebhuka čim postanu dostupne. Možete i precizno da odredite koje će se objave slati tako što ćete postaviti ključne reči za filtriranje. Kada nova objava ispuni vaše kriterijume, biće poslata na krajnju tačku vebhuka kao POST zahtev u JSON formatu.

Format JSON sadržaja zahteva

Svaki POST zahtev poslat na vaš vebhuk sadržaće dva glavna elementa: post i feed.

Zahtev sadrži i metapodatke za identifikaciju poruke vebhuka. Polje version označava verziju Feeder API-ja za vebhuk koja se šalje. Verzija je uvek 2023-06-26 i biće ažurirana ako dođe do izmena koje nisu kompatibilne sa prethodnom verzijom.

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

Element post sadrži informacije o pojedinačnoj 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: vrednost polja published biće null ako RSS izvor ne navede ispravan datum objavljivanja.

Element feed sadrži informacije o izvoru iz kog potič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 možemo da dodamo još polja u ove objekte. Ako vam nešto nedostaje, javite nam.

Ponovni pokušaji

Ako zahtev ne uspe, Feeder će automatski pokušati ponovo. Ako POST zahtev ne dobije HTTP odgovor sa kodom između 200 i 399, pokušaćemo ponovo da ga pošaljemo prema sledećem rasporedu, izraženom u sekundama:

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

Imajte u vidu da se mehanizam ponovnih pokušaja pokreće samo nakon stvarnih događaja objavljivanja i ne primenjuje se na testna obaveštenja. Vremenski razmaci takođe mogu da se promene.

Otklanjanje grešaka

Ako dođe do grešaka, možete ih pronaći u evidenciji izvršavanja radnji. Otvorite pravilo koje ne radi i kliknite na „Otvori evidenciju grešaka“.

Tu ćete pronaći više detalja o neuspelim vebhukovima.

Kako da podesite vebhuk

Da biste podesili vebhuk:

1. Otvorite stranicu Pravila.
2. Napravite novo pravilo.
3. Unesite naziv, izvore i kriterijume.
4. U odeljku „Šta treba da se desi?“ izaberite „Objaviti na Webhook“.
5. Unesite URL vebhuka u predviđeno polje.
6. Da biste proverili da li je sve ispravno podešeno, kliknite na dugme „Pošalji test poruku“ da biste poslali testno obaveštenje na svoju krajnju tačku. Imajte u vidu da je ovo samo test i da se mehanizam ponovnih pokušaja neće pokrenuti ako ne uspe. Da bi se testna objava poslala, na nalogu morate imati najmanje jedan izvor sa objavama.

Bezbednost: verifikacija potpisa vebhuka

Da biste bili sigurni da dolazni zahtevi vebhuka zaista potiču od Feedera i da nisu izmenjeni, možete da proverite tajnu vrednost koja se generiše za svaki vebhuk. Svaki zahtev vebhuka sadržaće zaglavlje X-Feeder-Signature sa HMAC-SHA256 potpisom tela zahteva.

Kako funkcioniše

1. U podešavanjima pravila uključite opciju „Napredno“. U polju „Tajna vrednost vebhuka“ prikazaće se niz znakova.
2. Kada Feeder pošalje vebhuk na vašu krajnju tačku, izračunava HMAC-SHA256 heš JSON tela zahteva, koristeći vašu tajnu vrednost kao ključ.
3. Dobijeni potpis se šalje u zaglavlju X-Feeder-Signature, sa prefiksom sha256=. Na primer:

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

4. Na serveru ponovo izračunajte isti HMAC-SHA256 heš koristeći sirovo telo zahteva i svoju kopiju tajne vrednosti, a zatim ga uporedite sa vrednošću u zaglavlju.

Zašto ovo koristiti?

• Autentičnost: potvrđuje da je zahtev poslao Feeder, a ne treća strana.
• Integritet: garantuje da sadržaj zahteva nije izmenjen tokom prenosa.

Verifikacija potpisa

Da biste verifikovali potpis:

1. Pročitajte sirovo telo zahteva kao string. Nemojte ga prvo parsirati.
2. Izračunajte HMAC-SHA256 tog stringa koristeći svoju tajnu vrednost.
3. Uporedite izračunati potpis sa vrednošću zaglavlja X-Feeder-Signature koristeći poređenje bez vremenskih razlika kako biste sprečili napade na osnovu vremena izvršavanja.

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

Važno: Za verifikaciju potpisa morate da pristupite sirovom telu zahteva. Ako vaš okvirni sistem prvo parsira JSON telo, ponovo serijalizovan string može da se razlikuje od originala, pa se potpis neće poklopiti. U Expressu koristite express.raw({ type: "application/json" }) na ruti vebhuka, kao što je prikazano iznad.

Još nešto?

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