Zelf integraties bouwen met webhooks

Met de regel ‘Plaats op Webhook’ stuur je nieuwe berichten uit RSS-feeds automatisch naar het webhook-endpoint dat je hebt opgegeven, zodra ze beschikbaar zijn. Je kunt ook instellen welke berichten worden verzonden door trefwoorden als filter te gebruiken. Zodra een nieuw bericht aan je criteria voldoet, wordt het als een POST-verzoek met JSON naar je webhook-endpoint gestuurd.

JSON-payloadformaat

Elk POST-verzoek naar je webhook bevat twee hoofdonderdelen: post en feed.

Het verzoek bevat ook metadata waarmee het webhookbericht kan worden geïdentificeerd. In het veld version staat welke versie van de Feeder-webhook-API wordt gebruikt. De versie is altijd 2023-06-26 en wordt aangepast als er wijzigingen worden doorgevoerd die niet compatibel zijn met eerdere versies.

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

Het onderdeel post bevat informatie over het afzonderlijke bericht:

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

Let op: published is null als de RSS-feed geen geldige publicatiedatum heeft opgegeven.

Het onderdeel feed bevat informatie over de feed waaruit het bericht afkomstig is:

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

Mogelijk voegen we in de toekomst velden aan deze objecten toe. Laat het ons weten als je iets mist.

Opnieuw proberen

Als een verzoek mislukt, probeert Feeder het automatisch opnieuw. Als een POST-verzoek geen HTTP-statuscode tussen 200 en 399 ontvangt, proberen we het volgens dit schema, met de tijden in seconden:

• Poging 1: na 5 seconden
• Poging 2: na 30 seconden
• Poging 3: na 60 seconden
• Poging 4: na 5 minuten
• Poging 5: na 10 minuten
• Poging 6: na 30 minuten
• Poging 7: na 30 minuten
• Poging 8: na 30 minuten

Dit mechanisme voor opnieuw proberen wordt alleen gestart bij echte gebeurtenisberichten, niet bij testmeldingen. De tijden kunnen ook veranderen.

Problemen opsporen

Als er fouten optreden, vind je die in het logboek met uitgevoerde acties. Ga naar de regel die niet werkt en klik op ‘Foutenlogboek openen’.

Daar vind je meer informatie over de mislukte webhookverzoeken.

Je webhook instellen

Zo stel je je webhook in:

1. Ga naar de pagina Regels.
2. Maak een nieuwe regel.
3. Voeg een naam, feeds en criteria toe.
4. Kies in het gedeelte ‘Wat zou er moeten gebeuren?’ de optie ‘Plaats op Webhook’.
5. Voer de URL van je webhook in het daarvoor bestemde tekstveld in.
6. Je kunt controleren of alles goed is ingesteld door op de knop ‘Testbericht plaatsen’ te klikken. Hiermee stuur je een testmelding naar je endpoint. Dit is alleen een test. Als die mislukt, wordt het mechanisme voor opnieuw proberen niet gestart. Je account moet ook minstens één feed met berichten bevatten om het testbericht te kunnen verzenden.

Beveiliging: webhookhandtekeningen verifiëren

Je kunt het webhookgeheim controleren dat voor elke webhook wordt gegenereerd. Zo weet je zeker dat binnenkomende webhookverzoeken echt van Feeder komen en niet zijn gemanipuleerd. Elk webhookverzoek bevat een header X-Feeder-Signature met een HMAC-SHA256-handtekening van de hoofdtekst van het verzoek.

Zo werkt het

1. Schakel in de instellingen van je regel de optie ‘Geavanceerd’ in. Je ziet dan een tekenreeks in het veld ‘Webhookgeheim’.
2. Wanneer Feeder een webhook naar je endpoint stuurt, berekent het een HMAC-SHA256-hash van de JSON-hoofdtekst van het verzoek. Je geheim wordt daarbij als sleutel gebruikt.
3. De resulterende handtekening wordt met de prefix sha256= in de header X-Feeder-Signature verzonden. Bijvoorbeeld:

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

4. Bereken op je server dezelfde HMAC-SHA256-hash opnieuw met de ruwe hoofdtekst van het verzoek en je kopie van het geheim. Vergelijk de hash vervolgens met de waarde in de header.

Waarom is dit nuttig?

• Authenticiteit: bevestigt dat het verzoek door Feeder is verzonden en niet door een derde partij.
• Integriteit: garandeert dat de payload onderweg niet is aangepast.

De handtekening verifiëren

Zo verifieer je de handtekening:

1. Lees de ruwe hoofdtekst van het verzoek als een tekenreeks. Parseer deze niet eerst.
2. Bereken de HMAC-SHA256 van die tekenreeks met je geheim.
3. Vergelijk je berekende handtekening met de waarde in de header X-Feeder-Signature. Gebruik hiervoor een tijdveilige vergelijking om timingaanvallen te voorkomen.

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

Belangrijk: voor het verifiëren van de handtekening moet je de ruwe hoofdtekst van het verzoek gebruiken. Als je framework de JSON-hoofdtekst parseert voordat je de HMAC berekent, kan de opnieuw geserialiseerde tekenreeks afwijken van het origineel en komt de handtekening niet overeen. Gebruik in Express express.raw({ type: "application/json" }) op de webhookroute, zoals hierboven.

Verder nog iets?

Vragen? Mail ons op support@feeder.co.