Bygg egna integrationer med webhooks

Med regeln ”Posta till Webhook” kan du automatisera utskick av nya inlägg från RSS-flöden till en webhook-slutpunkt som du anger, så snart inläggen blir tillgängliga. Du kan också styra vilka inlägg som skickas genom att ange nyckelord att filtrera på. När ett nytt inlägg matchar dina kriterier skickas det till din webhook-slutpunkt som en POST-begäran med JSON-formaterat innehåll.

JSON-format för nyttolasten

Varje POST-begäran som skickas till din webhook innehåller två huvudelement: post och feed.

Den innehåller också metadata som identifierar webhook-meddelandet. Fältet version anger vilken version av Feeders webhook-API som används. Versionen är alltid 2023-06-26 och uppdateras om vi gör ändringar som inte är bakåtkompatibla.

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

Elementet post innehåller information om det enskilda inlägget:

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

Obs! published är null om RSS-flödet inte angav ett giltigt publiceringsdatum.

Elementet feed innehåller information om flödet som inlägget kommer från:

{
  "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 komma att lägga till fler fält i dessa objekt framöver. Hör av dig om du saknar något.

Återförsök

Om en begäran misslyckas försöker Feeder automatiskt igen. Om en POST-begäran inte får en HTTP-svarskod mellan 200 och 399 försöker vi skicka den igen enligt följande schema, angivet i sekunder:

• Försök 1: efter 5 sekunder
• Försök 2: efter 30 sekunder
• Försök 3: efter 60 sekunder
• Försök 4: efter 5 minuter
• Försök 5: efter 10 minuter
• Försök 6: efter 30 minuter
• Försök 7: efter 30 minuter
• Försök 8: efter 30 minuter

Observera att återförsöken bara utlöses av riktiga inläggshändelser och inte gäller testaviseringar. Tidsintervallen kan också ändras.

Felsökning

Om ett fel uppstår hittar du det i loggen över körningar av åtgärden. Öppna regeln som inte fungerar och välj ”Öppna fellogg”.

Där ser du mer information om webhook-anropen som misslyckades.

Konfigurera din webhook

Så här konfigurerar du din webhook:

1. Gå till sidan Regler.
2. Skapa en ny regel.
3. Ange namn, flöden och kriterier.
4. Under ”Vad ska hända?” väljer du ”Posta till Webhook”.
5. Ange webhook-URL:en i textfältet.
6. Om du vill kontrollera att allt är rätt konfigurerat kan du använda knappen ”Skicka testmeddelande” för att skicka en testavisering till din slutpunkt. Observera att det bara är ett test. Om det misslyckas startar inte återförsöken. För att testinlägget ska kunna skickas måste du ha minst ett flöde med inlägg på ditt konto.

Säkerhet: verifiera webhook-signaturer

Du kan verifiera den webhook-hemlighet som genereras för varje webhook för att säkerställa att inkommande webhook-anrop verkligen kommer från Feeder och inte har manipulerats. Varje webhook-anrop innehåller en X-Feeder-Signature-header med en HMAC-SHA256-signatur av begärans innehåll.

Så fungerar det

1. Aktivera alternativet ”Avancerad” i regelinställningarna. Då visas en sträng i fältet ”Webhook Secret”.
2. När Feeder skickar en webhook till din slutpunkt beräknas en HMAC-SHA256-hash av JSON-begärans innehåll, med din hemlighet som nyckel.
3. Den resulterande signaturen skickas i headern X-Feeder-Signature, med prefixet sha256=. Exempel:

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

4. På din server beräknar du samma HMAC-SHA256-hash igen med den råa begäranskroppen och din kopia av hemligheten. Jämför sedan resultatet med värdet i headern.

Varför använda detta?

• Äkthet: Bekräftar att begäran skickades av Feeder och inte av en tredje part.
• Integritet: Säkerställer att nyttolasten inte har ändrats under överföringen.

Verifiera signaturen

Så här verifierar du signaturen:

1. Läs in den råa begäranskroppen som en sträng, utan att först tolka den.
2. Beräkna HMAC-SHA256 för strängen med din hemlighet.
3. Jämför den beräknade signaturen med värdet i headern X-Feeder-Signature med en tidskonstant jämförelse för att förhindra timingattacker.

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

Viktigt: Du måste använda den råa begäranskroppen för att verifiera signaturen. Om ditt ramverk tolkar JSON-innehållet innan du beräknar HMAC kan den återskapade strängen skilja sig från originalet, vilket gör att signaturerna inte matchar. I Express använder du express.raw({ type: "application/json" }) på webhook-rutten, som i exemplet ovan.

Något mer?

Har du frågor? Mejla oss på support@feeder.co.