Eigene Integrationen mit Webhooks erstellen

Mit der Regel „An Webhook posten“ kannst du automatisch neue Beiträge aus RSS-Feeds an einen angegebenen Webhook-Endpunkt senden, sobald sie verfügbar sind. Über Stichwörter kannst du außerdem festlegen, welche Beiträge gesendet werden. Wenn ein neuer Beitrag deinen Kriterien entspricht, wird er als JSON-formatierte POST-Anfrage an deinen Webhook-Endpunkt gesendet.

JSON-Payload-Format

Jede POST-Anfrage an deinen Webhook enthält zwei Hauptelemente: post und feed.

Zusätzlich enthält sie Metadaten zur Identifizierung der Webhook-Nachricht. Das Feld version gibt an, welche Version der Feeder-Webhook-API verwendet wird. Die Version ist immer 2023-06-26 und wird aktualisiert, falls es Änderungen gibt, die nicht abwärtskompatibel sind.

{
  "version": "2023-06-26",
  "message_id": "Eine eindeutige UUID für diese Nachricht. Bei Wiederholungsversuchen bleibt sie gleich.",
  "feed": { ... },
  "post": { ... }
}

Das Element post enthält Informationen zum einzelnen Beitrag:

{
  "id": "Die eindeutige Kennung des Beitrags",
  "title": "Der Titel des Beitrags",
  "url": "Die URL, unter der der Beitrag aufgerufen werden kann",
  "published": "Datum und Uhrzeit der Veröffentlichung des Beitrags",
  "content": "Der Inhalt des Beitrags",
  "audio_url": "Link zu einer an den Beitrag angehängten MP3-Datei (falls vorhanden)",
  "image_url": "Link zu einem an den Beitrag angehängten Bild (falls vorhanden)
}

Hinweis: published ist null, wenn der RSS-Feed kein gültiges Veröffentlichungsdatum enthält.

Das Element feed enthält Informationen zum Feed, aus dem der Beitrag stammt:

{
  "id": "Die eindeutige Kennung des Feeds",
  "source_url": "Die URL der Quelle, zum Beispiel die URL des RSS- oder Atom-Feeds",
  "public_url": "Die vom Feed selbst angegebene öffentliche URL der Quelle",
  "title": "Der Titel des Feeds",
  "favicon": "Die URL des Favicons des Feeds"
}

Diese Objekte können künftig erweitert werden. Wenn dir etwas fehlt, sag uns bitte Bescheid.

Wiederholungsversuche

Wenn eine Anfrage fehlschlägt, versucht Feeder automatisch, sie erneut zu senden. Erhält eine POST-Anfrage keinen HTTP-Antwortcode zwischen 200 und 399, versuchen wir, sie nach folgendem Zeitplan erneut zu senden. Die Zeitangaben sind in Sekunden:

• 1. Versuch: nach 5 Sekunden
• 2. Versuch: nach 30 Sekunden
• 3. Versuch: nach 60 Sekunden
• 4. Versuch: nach 5 Minuten
• 5. Versuch: nach 10 Minuten
• 6. Versuch: nach 30 Minuten
• 7. Versuch: nach 30 Minuten
• 8. Versuch: nach 30 Minuten

Bitte beachte: Dieser Mechanismus für Wiederholungsversuche wird nur bei echten Beitragsereignissen ausgelöst, nicht bei Testbenachrichtigungen. Die Zeitabstände können sich außerdem ändern.

Fehlersuche

Fehler findest du im Protokoll der Aktionsausführungen. Öffne einfach die nicht funktionierende Regel und klicke auf „Fehlerprotokoll öffnen“.

Dort findest du weitere Details zu den fehlgeschlagenen Webhooks.

Webhook einrichten

So richtest du deinen Webhook ein:

1. Rufe die Seite Regeln auf.
2. Erstelle eine neue Regel.
3. Gib einen Namen ein und wähle Feeds und Kriterien aus.
4. Wähle im Abschnitt „Was sollte passieren?“ die Option „An Webhook posten“ aus.
5. Gib die URL deines Webhooks in das vorgesehene Textfeld ein.
6. Mit der Schaltfläche „Testnachricht posten“ kannst du prüfen, ob alles richtig eingerichtet ist. Dadurch wird eine Testbenachrichtigung an deinen Endpunkt gesendet. Beachte, dass es sich nur um einen Test handelt. Schlägt er fehl, werden keine Wiederholungsversuche ausgelöst. Damit die Testnachricht gesendet werden kann, muss deinem Konto mindestens ein Feed mit hinzugefügten Beiträgen zugeordnet sein.

Sicherheit: Webhook-Signaturen überprüfen

Damit du sicher sein kannst, dass eingehende Webhook-Anfragen tatsächlich von Feeder stammen und nicht manipuliert wurden, kannst du das für jeden Webhook generierte Webhook-Secret überprüfen. Jede Webhook-Anfrage enthält im Header X-Feeder-Signature eine HMAC-SHA256-Signatur des Anfrage-Bodys.

So funktioniert es

1. Aktiviere in den Regeleinstellungen die Option „Erweitert“. Im Feld „Webhook-Secret“ wird eine Zeichenfolge angezeigt.
2. Wenn Feeder einen Webhook an deinen Endpunkt sendet, berechnet Feeder mit deinem Secret als Schlüssel einen HMAC-SHA256-Hash des JSON-Anfrage-Bodys.
3. Die resultierende Signatur wird mit dem Präfix sha256= im Header X-Feeder-Signature gesendet. Zum Beispiel:

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

4. Berechne auf deinem Server denselben HMAC-SHA256-Hash anhand des unverarbeiteten Anfrage-Bodys und deiner Kopie des Secrets erneut. Vergleiche ihn anschließend mit dem Wert im Header.

Warum ist das sinnvoll?

• Echtheit: Bestätigt, dass die Anfrage von Feeder und nicht von Dritten gesendet wurde.
• Integrität: Stellt sicher, dass die Payload während der Übertragung nicht verändert wurde.

Signatur überprüfen

So überprüfst du die Signatur:

1. Lies den unverarbeiteten Anfrage-Body als Zeichenfolge ein, ohne ihn vorher zu parsen.
2. Berechne mit deinem Secret den HMAC-SHA256-Hash dieser Zeichenfolge.
3. Vergleiche deine berechnete Signatur mit dem Wert im Header X-Feeder-Signature. Verwende dazu einen zeitkonstanten Vergleich, um Timing-Angriffe zu verhindern.

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

Wichtig: Für die Signaturprüfung musst du auf den unverarbeiteten Anfrage-Body zugreifen. Wenn dein Framework den JSON-Body parst, bevor du den HMAC berechnest, kann sich die erneut serialisierte Zeichenfolge vom Original unterscheiden und die Signatur stimmt nicht mehr überein. Verwende in Express wie oben gezeigt express.raw({ type: "application/json" }) für die Webhook-Route.

Noch Fragen?

Fragen? Schreib uns an support@feeder.co.