Cum creezi integrări proprii cu webhook-uri

Regula „Postează la Webhook” automatizează trimiterea postărilor noi din fluxurile RSS către endpointul webhook specificat de tine, imediat ce acestea devin disponibile. Poți și să alegi mai precis ce postări se trimit, configurând cuvinte-cheie pentru filtrare. Când o postare nouă corespunde criteriilor tale, aceasta va fi trimisă către endpointul webhook sub forma unei cereri POST în format JSON.

Formatul payloadului JSON

Fiecare cerere POST trimisă către webhook conține două elemente principale: post și feed.

Cererea conține și elemente de metadate care identifică mesajul webhook. Câmpul version indică versiunea API-ului webhook Feeder trimisă. Versiunea este întotdeauna 2023-06-26 și va fi actualizată dacă apar modificări incompatibile cu versiunile anterioare.

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

Elementul post conține informații despre postarea respectivă:

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

Notă: published va avea valoarea null dacă fluxul RSS nu a specificat o dată de publicare validă.

Elementul feed oferă informații despre fluxul din care provine postarea:

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

Este posibil să adăugăm elemente la aceste obiecte în viitor. Dacă îți lipsește ceva, anunță-ne.

Logica reîncercărilor

Dacă o cerere eșuează, Feeder încearcă automat să o trimită din nou. Dacă o cerere POST nu primește un cod de răspuns HTTP între 200 și 399, vom încerca să o retrimitem conform programului de mai jos, exprimat în secunde:

• Reîncercarea 1: după 5 secunde
• Reîncercarea 2: după 30 de secunde
• Reîncercarea 3: după 60 de secunde
• Reîncercarea 4: după 5 minute
• Reîncercarea 5: după 10 minute
• Reîncercarea 6: după 30 de minute
• Reîncercarea 7: după 30 de minute
• Reîncercarea 8: după 30 de minute

Reține că mecanismul de reîncercare se declanșează numai pentru evenimente reale de publicare a unei postări și nu se aplică notificărilor de test. Intervalele pot fi, de asemenea, modificate.

Depanare

Dacă apar erori, le poți găsi în jurnalul execuțiilor acțiunii. Accesează regula care nu funcționează și apasă „Deschide jurnalul de erori”.

Acolo vei găsi mai multe detalii despre webhook-urile care au eșuat.

Configurarea webhook-ului

Pentru a configura webhook-ul:

1. Accesează pagina Reguli.
2. Creează o regulă nouă.
3. Adaugă numele, fluxurile și criteriile.
4. În secțiunea „Ce ar trebui să se întâmple?”, alege „Postează la Webhook”.
5. Introdu adresa URL a webhook-ului în câmpul de text.
6. Pentru a verifica dacă totul este configurat corect, poți folosi butonul „Trimite mesaj de test” pentru a trimite o notificare de test către endpointul tău. Reține că aceasta este doar o testare și, dacă eșuează, nu va declanșa logica de reîncercare. De asemenea, pentru a trimite postarea de test, trebuie să ai în cont cel puțin un flux cu postări.

Securitate: verificarea semnăturilor webhook

Pentru a te asigura că cererile webhook primite provin într-adevăr de la Feeder și nu au fost modificate, poți verifica secretul webhook generat pentru fiecare webhook. Fiecare cerere webhook va include un antet X-Feeder-Signature care conține o semnătură HMAC-SHA256 a corpului cererii.

Cum funcționează

1. În setările regulii, activează opțiunea „Avansat”. Vei vedea un șir în câmpul „Secret webhook”.
2. Când Feeder trimite un webhook către endpointul tău, calculează un hash HMAC-SHA256 al corpului cererii JSON, folosind secretul tău drept cheie.
3. Semnătura rezultată este trimisă în antetul X-Feeder-Signature, cu prefixul sha256=. De exemplu:

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

4. Pe serverul tău, recalculează același hash HMAC-SHA256 folosind corpul brut al cererii și copia ta a secretului, apoi compară-l cu valoarea din antet.

De ce să folosești această verificare?

• Autenticitate: confirmă că cererea a fost trimisă de Feeder, nu de o terță parte.
• Integritate: garantează că payloadul nu a fost modificat în timpul transmiterii.

Verificarea semnăturii

Pentru verificare:

1. Citește corpul brut al cererii ca șir de caractere, fără să îl analizezi mai întâi.
2. Calculează HMAC-SHA256 pentru șirul respectiv, folosind secretul tău.
3. Compară semnătura calculată cu valoarea din antetul X-Feeder-Signature folosind o comparație sigură în timp, pentru a preveni atacurile de tip timing.

Exemplu: 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: Pentru verificarea semnăturii, trebuie să accesezi corpul brut al cererii. Dacă framework-ul analizează corpul JSON înainte să calculezi HMAC-ul, șirul serializat din nou poate fi diferit de original, iar semnătura nu va corespunde. În Express, folosește express.raw({ type: "application/json" }) pe ruta webhook, ca în exemplul de mai sus.

Mai ai întrebări?

Întrebări? Scrie-ne la support@feeder.co.