Crea integracions pròpies amb webhooks

La regla «Publica a Webhook» et permet automatitzar l’enviament de les publicacions noves dels canals RSS a l’endpoint de webhook que indiquis, tan bon punt estiguin disponibles. També pots ajustar quines publicacions s’envien configurant paraules clau per filtrar-les. Quan una publicació nova compleixi els criteris, s’enviarà a l’endpoint de webhook com una petició POST en format JSON.

Format de la càrrega JSON

Cada petició POST enviada al webhook conté dos elements principals: post i feed.

També conté metadades per identificar el missatge del webhook. El camp version indica quina versió de l’API de webhooks de Feeder s’envia. La versió és sempre 2023-06-26 i s’actualitzarà si hi ha canvis incompatibles.

{
  "version": "2023-06-26",
  "message_id": "un UUID únic per a aquest missatge, que es manté igual durant els intents de reenviament",
  "feed": { ... },
  "post": { ... }
}

L’element post conté informació sobre la publicació individual:

{
  "id": "L'identificador únic de la publicació",
  "title": "El títol de la publicació",
  "url": "L'URL on es pot consultar la publicació",
  "published": "La data i l'hora de publicació",
  "content": "El contingut de la publicació",
  "audio_url": "Enllaç a l'MP3 adjunt a la publicació (si n'hi ha)",
  "image_url": "Enllaç a la imatge adjunta a la publicació (si n'hi ha)
}

Nota: published serà null si el canal RSS no especifica una data de publicació vàlida.

L’element feed proporciona informació sobre el canal d’on prové la publicació:

{
  "id": "L'identificador únic del canal",
  "source_url": "L'URL de la font, per exemple, l'URL del canal RSS/Atom",
  "public_url": "L'URL públic que el canal declara com a propi",
  "title": "El títol del canal",
  "favicon": "L'URL de la icona del canal"
}

És possible que en el futur afegim elements a aquests objectes. Si trobes a faltar alguna dada, fes-nos-ho saber.

Lògica dels intents de reenviament

Si una petició falla, Feeder la torna a provar automàticament. Si una petició POST no rep un codi de resposta HTTP entre 200 i 399, intentarem reenviar-la segons aquest calendari, definit en segons:

• Intent 1: al cap de 5 segons
• Intent 2: al cap de 30 segons
• Intent 3: al cap de 60 segons
• Intent 4: al cap de 5 minuts
• Intent 5: al cap de 10 minuts
• Intent 6: al cap de 30 minuts
• Intent 7: al cap de 30 minuts
• Intent 8: al cap de 30 minuts

Tingues en compte que aquest mecanisme de reenviament només s’activa quan hi ha una publicació real i no s’aplica a les notificacions de prova. Els intervals també poden canviar.

Resolució de problemes

Si es produeixen errors, els pots consultar al registre d’execució de l’acció. Ves a la regla que no funciona i fes clic a «Obre el registre d’errors».

Allà hi trobaràs més detalls sobre els webhooks que han fallat.

Configura el webhook

Per configurar el webhook:

1. Ves a la pàgina de Regles.
2. Crea una regla nova.
3. Afegeix-hi el nom, els canals i els criteris.
4. A la secció «Què ha de passar?», tria «Publica a Webhook».
5. Introdueix l’URL del webhook al camp de text corresponent.
6. Per comprovar que tot està ben configurat, pots fer servir el botó «Envia un missatge de prova» per enviar una notificació de prova al teu endpoint. Tingues en compte que només és una prova i, si falla, no s’iniciarà la lògica de reenviament. A més, perquè s’enviï la publicació de prova, has de tenir almenys un canal amb publicacions afegit al compte.

Seguretat: verifica les signatures dels webhooks

Per assegurar-te que les peticions de webhook entrants provenen realment de Feeder i que no s’han manipulat, pots verificar el secret del webhook que es genera per a cada webhook. Totes les peticions de webhook inclouen una capçalera X-Feeder-Signature amb una signatura HMAC-SHA256 del cos de la petició.

Com funciona

1. A la configuració de la regla, activa l’opció «Avançat». Veuràs una cadena al camp «Secret del webhook».
2. Quan Feeder envia un webhook al teu endpoint, calcula un hash HMAC-SHA256 del cos de la petició JSON i fa servir el teu secret com a clau.
3. La signatura resultant s’envia a la capçalera X-Feeder-Signature, amb el prefix sha256=. Per exemple:

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

4. Al servidor, torna a calcular el mateix hash HMAC-SHA256 amb el cos brut de la petició i la teva còpia del secret, i després compara’l amb el valor de la capçalera.

Per què fer-ho?

• Autenticitat: confirma que Feeder ha enviat la petició i no pas un tercer.
• Integritat: garanteix que la càrrega no s’ha modificat durant la transmissió.

Verifica la signatura

Per verificar-la:

1. Llegeix el cos brut de la petició com una cadena de text, sense analitzar-lo primer.
2. Calcula l’HMAC-SHA256 d’aquesta cadena amb el teu secret.
3. Compara la signatura calculada amb el valor de la capçalera X-Feeder-Signature mitjançant una comparació segura pel que fa al temps d’execució per evitar atacs de temporització.

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: has d’accedir al cos brut de la petició per verificar la signatura. Si el framework analitza el cos JSON abans que calculis l’HMAC, la cadena serialitzada de nou pot ser diferent de l’original i la signatura no coincidirà. A Express, fes servir express.raw({ type: "application/json" }) a la ruta del webhook, tal com es mostra més amunt.

Encara tens dubtes?

Tens preguntes? Escriu-nos a support@feeder.co.