Lag dine egne integrasjoner med webhooks

Med regelen «Post til Webhook» kan du automatisere sendingen av nye innlegg fra RSS-strømmer til webhook-endepunktet du angir, så snart innleggene blir tilgjengelige. Du kan også finjustere hvilke innlegg som sendes, ved å angi nøkkelord som det skal filtreres på. Når et nytt innlegg oppfyller kriteriene dine, sendes det til webhook-endepunktet ditt som en POST-forespørsel i JSON-format.

JSON-format for nyttelast

Hver POST-forespørsel som sendes til webhooken, inneholder to hovedelementer: post og feed.

Forespørselen inneholder også metadata som identifiserer webhook-meldingen. Feltet version angir hvilken versjon av Feeder Webhook API som brukes. Versjonen er alltid 2023-06-26 og oppdateres hvis det gjøres endringer som ikke er bakoverkompatible.

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

Elementet post inneholder informasjon om det enkelte innlegget:

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

Merk: published er null hvis RSS-strømmen ikke oppga en gyldig publiseringsdato.

Elementet feed inneholder informasjon om strømmen innlegget kommer fra:

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

Vi kan komme til å legge til flere felt i disse objektene senere. Gi oss beskjed hvis det er noe du savner.

Logikk for nye forsøk

Hvis en forespørsel mislykkes, prøver Feeder automatisk på nytt. Hvis en POST-forespørsel ikke får en HTTP-statuskode mellom 200 og 399, prøver vi å sende den på nytt etter en bestemt tidsplan, angitt i sekunder:

• Forsøk 1: etter 5 sekunder
• Forsøk 2: etter 30 sekunder
• Forsøk 3: etter 60 sekunder
• Forsøk 4: etter 5 minutter
• Forsøk 5: etter 10 minutter
• Forsøk 6: etter 30 minutter
• Forsøk 7: etter 30 minutter
• Forsøk 8: etter 30 minutter

Merk at denne mekanismen for nye forsøk bare utløses av faktiske innleggshendelser, og ikke gjelder testvarsler. Tidspunktene kan også bli endret.

Feilsøking

Hvis det oppstår feil, finner du dem i loggen for regelkjøringer. Gå til regelen som ikke fungerer, og velg «Open error log».

Der finner du flere detaljer om webhookene som mislyktes.

Konfigurer webhooken

Slik konfigurerer du webhooken:

1. Gå til siden Regler.
2. Opprett en ny regel.
3. Legg til navn, strømmer og kriterier.
4. Velg «Post til Webhook» under «Hva skal skje?».
5. Skriv inn webhook-URL-en din i tekstfeltet.
6. For å kontrollere at alt er riktig konfigurert kan du bruke knappen «Post testmelding» til å sende et testvarsel til endepunktet ditt. Merk at dette bare er en test, og at den ikke utløser logikken for nye forsøk hvis den mislykkes. For at testinnlegget skal sendes, må du ha minst én strøm med innlegg lagt til på kontoen din.

Sikkerhet: Verifiser webhook-signaturer

For å kontrollere at innkommende webhook-forespørsler faktisk kommer fra Feeder og ikke er blitt manipulert, kan du verifisere webhook-hemmeligheten som genereres for hver webhook. Hver webhook-forespørsel inneholder en X-Feeder-Signature-header med en HMAC-SHA256-signatur av forespørselens innhold.

Slik fungerer det

1. Slå på alternativet «Avansert» i regelinnstillingene. Da vises en streng i feltet «Webhook Secret».
2. Når Feeder sender en webhook til endepunktet ditt, beregner Feeder en HMAC-SHA256-hash av JSON-innholdet i forespørselen, med hemmeligheten din som nøkkel.
3. Den resulterende signaturen sendes i X-Feeder-Signature-headeren, med prefikset sha256=. For eksempel:

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

4. På serveren beregner du den samme HMAC-SHA256-hashen på nytt med den opprinnelige forespørselsteksten og din kopi av hemmeligheten, og sammenligner den deretter med verdien i headeren.

Hvorfor bruke dette?

• Autentisitet: Bekrefter at forespørselen ble sendt av Feeder, ikke av en tredjepart.
• Integritet: Sikrer at nyttelasten ikke er blitt endret under overføringen.

Verifiser signaturen

Slik verifiserer du signaturen:

1. Les inn den opprinnelige forespørselsteksten som en streng. Ikke analyser den først.
2. Beregn HMAC-SHA256 av strengen ved hjelp av hemmeligheten din.
3. Sammenlign den beregnede signaturen med verdien i X-Feeder-Signature-headeren ved hjelp av en tidsuavhengig sammenligning for å forhindre timingangrep.

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

Viktig: Du må bruke den opprinnelige forespørselsteksten når du verifiserer signaturen. Hvis rammeverket ditt analyserer JSON-innholdet før du beregner HMAC-en, kan den serialiserte strengen være forskjellig fra originalen, og signaturen vil ikke stemme. I Express bruker du express.raw({ type: "application/json" }) på webhook-ruten, som vist ovenfor.

Noe mer?

Har du spørsmål? Send oss en e-post på support@feeder.co.