Créer vos propres intégrations avec des webhooks

La règle « Publier sur Webhook » vous permet d’automatiser l’envoi des nouvelles publications de vos flux RSS vers le point de terminaison de webhook de votre choix, dès qu’elles sont disponibles. Vous pouvez également affiner les publications envoyées en définissant des mots-clés de filtrage. Lorsqu’une nouvelle publication correspond à vos critères, elle est envoyée à votre point de terminaison sous la forme d’une requête POST au format JSON.

Format des données JSON

Chaque requête POST envoyée à votre webhook contient deux éléments principaux : post et feed.

Elle contient également des métadonnées permettant d’identifier le message du webhook. Le champ version indique la version de l’API de webhook Feeder utilisée. Sa valeur reste 2023-06-26 et sera mise à jour en cas de modifications incompatibles.

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

L’élément post contient des informations sur la publication :

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

Remarque : published vaut null si le flux RSS ne précise pas de date de publication valide.

L’élément feed fournit des informations sur le flux d’origine de la publication :

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

Nous pourrons ajouter des éléments à ces objets à l’avenir. Si une information vous manque, n’hésitez pas à nous le signaler.

Nouvelle tentative en cas d’échec

En cas d’échec d’une requête, Feeder la renvoie automatiquement. Si une requête POST ne reçoit pas de code de réponse HTTP compris entre 200 et 399, nous tentons de la renvoyer selon le calendrier suivant, exprimé en secondes :

• 1re tentative : après 5 secondes
• 2e tentative : après 30 secondes
• 3e tentative : après 60 secondes
• 4e tentative : après 5 minutes
• 5e tentative : après 10 minutes
• 6e tentative : après 30 minutes
• 7e tentative : après 30 minutes
• 8e tentative : après 30 minutes

Notez que ce mécanisme de nouvelle tentative ne se déclenche qu’à la suite d’événements réels liés à une publication. Il ne s’applique pas aux notifications de test. Les délais peuvent également changer.

Résoudre les problèmes

En cas d’erreur, vous pouvez la consulter dans le journal d’exécution de l’action. Ouvrez la règle qui ne fonctionne pas, puis cliquez sur « Ouvrir le journal des erreurs ».

Vous y trouverez davantage de détails sur les webhooks qui ont échoué.

Configurer votre webhook

Pour configurer votre webhook :

1. Accédez à la page Règles.
2. Créez une nouvelle règle.
3. Indiquez son nom, les flux et les critères.
4. Dans la section « Que devrait-il se passer ? », choisissez « Publier sur Webhook ».
5. Saisissez l’URL de votre webhook dans le champ prévu à cet effet.
6. Pour vérifier que tout est correctement configuré, vous pouvez utiliser le bouton « Poster un message de test » afin d’envoyer une notification de test à votre point de terminaison. Notez qu’il s’agit uniquement d’un test et que le mécanisme de nouvelle tentative ne se déclenchera pas en cas d’échec. Pour envoyer le message de test, vous devez également avoir au moins un flux avec des publications dans votre compte.

Sécurité : vérifier les signatures de webhook

Pour vous assurer que les requêtes de webhook reçues proviennent bien de Feeder et qu’elles n’ont pas été modifiées, vous pouvez vérifier le secret généré pour chaque webhook. Chaque requête de webhook comporte un en-tête X-Feeder-Signature contenant une signature HMAC-SHA256 du corps de la requête.

Comment ça fonctionne

1. Dans les paramètres de votre règle, activez l’option « Avancé ». Une chaîne de caractères s’affiche dans le champ « Secret du webhook ».
2. Lorsque Feeder envoie un webhook à votre point de terminaison, il calcule une empreinte HMAC-SHA256 du corps de la requête JSON en utilisant votre secret comme clé.
3. La signature obtenue est envoyée dans l’en-tête X-Feeder-Signature, précédée de sha256=. Par exemple :

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

4. Sur votre serveur, recalculez la même empreinte HMAC-SHA256 à partir du corps brut de la requête et de votre copie du secret, puis comparez-la à la valeur de l’en-tête.

Pourquoi l’utiliser ?

• Authenticité : confirme que la requête a été envoyée par Feeder, et non par un tiers.
• Intégrité : garantit que les données n’ont pas été modifiées pendant leur transmission.

Vérifier la signature

Pour vérifier la signature :

1. Lisez le corps brut de la requête sous forme de chaîne de caractères, sans l’analyser au préalable.
2. Calculez le HMAC-SHA256 de cette chaîne à l’aide de votre secret.
3. Comparez la signature calculée à la valeur de l’en-tête X-Feeder-Signature à l’aide d’une comparaison à temps constant afin d’éviter les attaques par mesure du temps.

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

Important : vous devez accéder au corps brut de la requête pour vérifier la signature. Si votre framework analyse le corps JSON avant le calcul du HMAC, la chaîne reconstruite peut différer de la chaîne d’origine et la signature ne correspondra pas. Dans Express, utilisez express.raw({ type: "application/json" }) sur la route du webhook, comme dans l’exemple ci-dessus.

Autre question ?

Des questions ? Écrivez-nous à support@feeder.co.