Crea integrazioni personalizzate con i webhook

La regola «Pubblica su Webhook» ti permette di automatizzare l’invio dei nuovi post dei feed RSS all’endpoint webhook che hai specificato, non appena sono disponibili. Puoi anche scegliere quali post inviare impostando parole chiave da usare come filtri. Quando un nuovo post corrisponde ai criteri, viene inviato all’endpoint webhook con una richiesta POST in formato JSON.

Formato del payload JSON

Ogni richiesta POST inviata al webhook contiene due elementi principali: post e feed.

La richiesta include anche alcuni metadati che identificano il messaggio webhook. Il campo version indica la versione dell’API webhook di Feeder utilizzata. La versione è sempre 2023-06-26 e verrà aggiornata in caso di modifiche non compatibili con le versioni precedenti.

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

L’elemento post contiene informazioni sul singolo post:

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

Nota: published avrà valore null se il feed RSS non specifica una data di pubblicazione valida.

L’elemento feed fornisce informazioni sul feed da cui proviene il post:

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

In futuro potremmo aggiungere altri campi a questi oggetti. Se ti manca qualche dato, faccelo sapere.

Nuovi tentativi

Se una richiesta non va a buon fine, Feeder la invia di nuovo automaticamente. Se una richiesta POST non riceve un codice di risposta HTTP compreso tra 200 e 399, proveremo a inviarla di nuovo secondo il seguente programma, con tempi espressi in secondi:

• Primo tentativo: dopo 5 secondi
• Secondo tentativo: dopo 30 secondi
• Terzo tentativo: dopo 60 secondi
• Quarto tentativo: dopo 5 minuti
• Quinto tentativo: dopo 10 minuti
• Sesto tentativo: dopo 30 minuti
• Settimo tentativo: dopo 30 minuti
• Ottavo tentativo: dopo 30 minuti

Tieni presente che questo meccanismo di nuovi tentativi si attiva solo in seguito a eventi reali relativi ai post e non si applica alle notifiche di test. Anche gli intervalli potrebbero cambiare.

Diagnostica

Se si verificano errori, puoi trovarli nel registro delle esecuzioni dell’azione. Apri la regola che non funziona e seleziona «Apri registro errori».

Qui troverai maggiori dettagli sui webhook che non sono andati a buon fine.

Configura il webhook

Per configurare il webhook:

1. Vai alla pagina Regole.
2. Crea una nuova regola.
3. Inserisci il nome, i feed e i criteri.
4. Nella sezione «Cosa dovrebbe succedere?», scegli «Pubblica su Webhook».
5. Inserisci l’URL del webhook nel campo di testo.
6. Per verificare che tutto sia configurato correttamente, puoi selezionare il pulsante «Invia messaggio di test» per inviare una notifica di prova al tuo endpoint. Tieni presente che si tratta solo di un test: se non va a buon fine, non verrà avviato il meccanismo dei nuovi tentativi. Inoltre, per inviare il post di test, devi avere almeno un feed con post aggiunti al tuo account.

Sicurezza: verifica delle firme webhook

Per assicurarti che le richieste webhook in arrivo provengano davvero da Feeder e non siano state manomesse, puoi verificare il segreto webhook generato per ciascun webhook. Ogni richiesta webhook include un header X-Feeder-Signature contenente una firma HMAC-SHA256 del corpo della richiesta.

Come funziona

1. Nelle impostazioni della regola, attiva l’opzione «Avanzato». Nel campo «Segreto webhook» vedrai una stringa.
2. Quando Feeder invia un webhook al tuo endpoint, calcola un hash HMAC-SHA256 del corpo della richiesta JSON, usando il tuo segreto come chiave.
3. La firma risultante viene inviata nell’header X-Feeder-Signature, preceduta da sha256=. Per esempio:

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

4. Sul tuo server, calcola di nuovo lo stesso hash HMAC-SHA256 usando il corpo grezzo della richiesta e la copia del tuo segreto, quindi confrontalo con il valore nell’header.

Perché usarla?

• Autenticità: conferma che la richiesta è stata inviata da Feeder e non da terzi.
• Integrità: garantisce che il payload non sia stato modificato durante la trasmissione.

Verifica della firma

Per verificare la firma:

1. Leggi il corpo grezzo della richiesta come stringa, senza analizzarlo prima.
2. Calcola l’HMAC-SHA256 della stringa usando il tuo segreto.
3. Confronta la firma calcolata con il valore dell’header X-Feeder-Signature usando un confronto a tempo costante per prevenire gli attacchi temporali.

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

Importante: per verificare la firma devi accedere al corpo grezzo della richiesta. Se il framework analizza il corpo JSON prima che tu calcoli l’HMAC, la stringa serializzata di nuovo potrebbe essere diversa dall’originale e la firma non corrisponderebbe. In Express, usa express.raw({ type: "application/json" }) sulla route del webhook, come nell’esempio qui sopra.

Hai altre domande?

Hai domande? Scrivici a support@feeder.co.