Omien integraatioiden rakentaminen webhookien avulla

Lähetä Webhookiin -säännöllä voit automatisoida uusien RSS-syötejulkaisujen lähettämisen määrittämääsi webhook-päätepisteeseen heti, kun julkaisut ovat saatavilla. Voit myös rajata lähetettäviä julkaisuja määrittämällä suodatukseen käytettäviä avainsanoja. Kun uusi julkaisu vastaa ehtojasi, se lähetetään webhook-päätepisteeseesi JSON-muotoisena POST-pyyntönä.

JSON-tietosisällön muoto

Jokainen webhookiin lähetettävä POST-pyyntö sisältää kaksi pääosaa: post ja feed.

Pyynnössä on myös metatietoja, joiden avulla webhook-viesti voidaan tunnistaa. version-kenttä kertoo, mitä Feederin webhook-rajapinnan versiota käytetään. Versio on aina 2023-06-26, ja sitä päivitetään, jos tehdään yhteensopivuutta rikkovia muutoksia.

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

post-osa sisältää yksittäistä julkaisua koskevat tiedot:

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

Huomaa, että published-arvo on null, jos RSS-syöte ei määritä kelvollista julkaisuajankohtaa.

feed-osa sisältää tiedot syötteestä, josta julkaisu on peräisin:

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

Saatamme lisätä näihin objekteihin tietoja myöhemmin. Jos jokin tarvitsemasi tieto puuttuu, kerro siitä meille.

Uudelleenyritykset

Jos pyyntö epäonnistuu, Feeder yrittää lähettää sen automaattisesti uudelleen. Jos POST-pyyntö ei saa HTTP-vastauskoodia väliltä 200–399, yritämme lähettää sen uudelleen seuraavan aikataulun mukaan. Ajat ovat sekunteina, ellei toisin mainita:

• Uudelleenyritys 1: 5 sekunnin kuluttua
• Uudelleenyritys 2: 30 sekunnin kuluttua
• Uudelleenyritys 3: 60 sekunnin kuluttua
• Uudelleenyritys 4: 5 minuutin kuluttua
• Uudelleenyritys 5: 10 minuutin kuluttua
• Uudelleenyritys 6: 30 minuutin kuluttua
• Uudelleenyritys 7: 30 minuutin kuluttua
• Uudelleenyritys 8: 30 minuutin kuluttua

Huomaa, että uudelleenyritysmekanismi käynnistyy vain varsinaisten julkaisujen yhteydessä, eikä se koske testiviestejä. Aikataulu voi myös muuttua.

Virheiden selvittäminen

Jos tapahtuu virheitä, löydät ne toiminnon suorituslokista. Avaa ongelmallinen sääntö ja valitse ”Avaa virheloki”.

Näet sieltä lisätietoja epäonnistuneista webhookeista.

Webhookin määrittäminen

Määritä webhook seuraavasti:

1. Siirry Säännöt-sivulle.
2. Luo uusi sääntö.
3. Lisää säännölle nimi sekä valitse syötteet ja ehdot.
4. Valitse ”Mitä pitäisi tapahtua?” -osiossa ”Lähetä Webhookiin”.
5. Kirjoita webhook-osoitteesi sille varattuun tekstikenttään.
6. Voit varmistaa määritysten oikeellisuuden lähettämällä päätepisteeseesi testiviestin ”Lähetä testiviesti” -painikkeella. Huomaa, että kyseessä on vain testi. Epäonnistunut testiviesti ei käynnistä uudelleenyrityksiä. Testiviestin lähettämistä varten tilillesi on lisättävä vähintään yksi syöte, jossa on julkaisuja.

Tietoturva: webhook-allekirjoitusten tarkistaminen

Voit varmistaa, että saapuvat webhook-pyynnöt ovat todella Feederiltä eikä niiden sisältöä ole muutettu, tarkistamalla kullekin webhookille luodun salaisuuden avulla pyynnön allekirjoituksen. Jokainen webhook-pyyntö sisältää X-Feeder-Signature-otsakkeen, jossa on pyynnön rungosta laskettu HMAC-SHA256-allekirjoitus.

Näin se toimii

1. Ota säännön asetuksissa ”Edistynyt”-valinta käyttöön. ”Webhook-salaisuus”-kentässä näkyy merkkijono.
2. Kun Feeder lähettää webhookin päätepisteeseesi, se laskee JSON-pyynnön rungosta HMAC-SHA256-tiivisteen käyttäen salaisuuttasi avaimena.
3. Allekirjoitus lähetetään X-Feeder-Signature-otsakkeessa, ja sen alussa on sha256=. Esimerkki:

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

4. Laske palvelimellasi sama HMAC-SHA256-tiiviste pyynnön raakamuotoisesta rungosta ja hallussasi olevasta salaisuudesta. Vertaa sitten tulosta otsakkeen arvoon.

Miksi tätä kannattaa käyttää?

• Alkuperän varmistaminen: Vahvistaa, että pyynnön lähetti Feeder eikä kolmas osapuoli.
• Eheys: Varmistaa, ettei tietosisältöä ole muutettu siirron aikana.

Allekirjoituksen tarkistaminen

Tarkista allekirjoitus näin:

1. Lue pyynnön raakamuotoinen runko merkkijonona. Älä jäsennä sitä ensin.
2. Laske merkkijonon HMAC-SHA256-tiiviste salaisuuttasi käyttäen.
3. Vertaa laskemaasi allekirjoitusta X-Feeder-Signature-otsakkeen arvoon ajoitushyökkäykset kestävällä vertailulla.

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

Tärkeää: Allekirjoituksen tarkistamista varten sinun on käytettävä pyynnön raakamuotoista runkoa. Jos käyttämäsi kehys jäsentää JSON-rungon ennen HMAC-tiivisteen laskemista, uudelleen muodostettu merkkijono voi poiketa alkuperäisestä, jolloin allekirjoitukset eivät täsmää. Expressissä webhook-reitillä tulee käyttää yllä olevan esimerkin tapaan express.raw({ type: "application/json" })-määritystä.

Onko vielä kysyttävää?

Kysyttävää? Lähetä meille sähköpostia osoitteeseen support@feeder.co.