Kā izveidot pielāgotas integrācijas ar webhook

Noteikums “Nosūtīt uz Webhook” ļauj automatizēt jaunu RSS plūsmas ierakstu nosūtīšanu uz norādīto webhook galapunktu, tiklīdz tie ir pieejami. Varat arī izvēlēties, kurus ierakstus sūtīt, iestatot filtrēšanas atslēgvārdus. Jauns ieraksts, kas atbilst jūsu kritērijiem, tiks nosūtīts uz webhook galapunktu kā POST pieprasījums JSON formātā.

JSON datu struktūra

Katrā POST pieprasījumā, kas tiek nosūtīts uz jūsu webhook, ir divi galvenie elementi: post un feed.

Tajā ir arī metadati, pēc kuriem var identificēt webhook ziņojumu. Lauks version norāda izmantoto Feeder webhook API versiju. Versija vienmēr ir 2023-06-26, un tā tiks atjaunināta, ja tiks veiktas nesaderīgas izmaiņas.

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

Elements post satur informāciju par konkrēto ierakstu:

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

Piezīme: published vērtība būs null, ja RSS plūsmā nav norādīts derīgs publicēšanas datums.

Elements feed sniedz informāciju par plūsmu, no kuras ir iegūts ieraksts:

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

Nākotnē šajos objektos var tikt pievienoti jauni lauki. Ja jums kaut kā trūkst, lūdzu, sazinieties ar mums.

Atkārtoti mēģinājumi

Ja pieprasījums neizdodas, Feeder to automātiski nosūta atkārtoti. Ja POST pieprasījums nesaņem HTTP atbildes kodu no 200 līdz 399, mēģināsim to nosūtīt vēlreiz saskaņā ar tālāk norādīto grafiku. Laiks norādīts sekundēs:

• 1. mēģinājums: pēc 5 sekundēm
• 2. mēģinājums: pēc 30 sekundēm
• 3. mēģinājums: pēc 60 sekundēm
• 4. mēģinājums: pēc 5 minūtēm
• 5. mēģinājums: pēc 10 minūtēm
• 6. mēģinājums: pēc 30 minūtēm
• 7. mēģinājums: pēc 30 minūtēm
• 8. mēģinājums: pēc 30 minūtēm

Ņemiet vērā, ka atkārtotas sūtīšanas mehānisms tiek aktivizēts tikai tad, kad ir reāls ieraksta notikums, un neattiecas uz testa paziņojumiem. Arī laika intervāli var mainīties.

Kļūdu novēršana

Ja rodas kļūdas, tās varat atrast darbību izpildes žurnālā. Atveriet noteikumu, kas nedarbojas, un nospiediet “Atvērt kļūdu žurnālu”.

Tur būs redzama plašāka informācija par webhook pieprasījumiem, kas neizdevās.

Webhook iestatīšana

Lai iestatītu webhook:

1. Atveriet lapu Noteikumi.
2. Izveidojiet jaunu noteikumu.
3. Norādiet nosaukumu, plūsmas un kritērijus.
4. Sadaļā “Kas jānotiek?” izvēlieties “Nosūtīt uz Webhook”.
5. Norādītajā teksta laukā ievadiet sava webhook URL.
6. Lai pārliecinātos, ka viss ir iestatīts pareizi, varat nospiest pogu “Nosūtīt testa ziņojumu”, lai nosūtītu testa paziņojumu uz savu galapunktu. Ņemiet vērā, ka tas ir tikai tests. Ja tas neizdodas, atkārtotas sūtīšanas mehānisms netiks aktivizēts. Lai testa ierakstu varētu nosūtīt, jūsu kontā jābūt vismaz vienai plūsmai ar pievienotiem ierakstiem.

Drošība: webhook parakstu pārbaude

Lai pārliecinātos, ka ienākošie webhook pieprasījumi patiešām ir no Feeder un nav mainīti, varat pārbaudīt katram webhook ģenerēto slepeno atslēgu. Katrā webhook pieprasījumā būs galvene X-Feeder-Signature ar pieprasījuma pamatdaļas HMAC-SHA256 parakstu.

Darbības princips

1. Noteikuma iestatījumos ieslēdziet opciju “Paplašināti”. Laukā “Webhook Secret” būs redzama virkne.
2. Kad Feeder nosūta webhook pieprasījumu uz jūsu galapunktu, tas aprēķina JSON pieprasījuma pamatdaļas HMAC-SHA256 jaucējkodu, kā atslēgu izmantojot jūsu slepeno atslēgu.
3. Aprēķinātais paraksts tiek nosūtīts galvenē X-Feeder-Signature, pirms tā pievienojot prefiksu sha256=. Piemēram:

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

4. Serverī no jauna aprēķiniet to pašu HMAC-SHA256 jaucējkodu, izmantojot neapstrādāto pieprasījuma pamatdaļu un savu slepenās atslēgas kopiju, pēc tam salīdziniet to ar galvenes vērtību.

Kāpēc to izmantot?

• Autentiskums: apstiprina, ka pieprasījumu nosūtījis Feeder, nevis trešā puse.
• Integritāte: garantē, ka pārsūtīšanas laikā datu struktūra nav mainīta.

Paraksta pārbaude

Lai pārbaudītu parakstu:

1. Nolasiet neapstrādāto pieprasījuma pamatdaļu kā virkni, vispirms to neparsējot.
2. Aprēķiniet šīs virknes HMAC-SHA256, izmantojot savu slepeno atslēgu.
3. Salīdziniet aprēķināto parakstu ar galvenes X-Feeder-Signature vērtību, izmantojot laika ziņā drošu salīdzināšanu, lai novērstu laika uzbrukumus.

Piemērs: 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);
  }
);

Svarīgi: Lai pārbaudītu parakstu, jāizmanto neapstrādātā pieprasījuma pamatdaļa. Ja jūsu ietvars JSON pamatdaļu parsē pirms HMAC aprēķināšanas, atkārtoti serializētā virkne var atšķirties no sākotnējās, un paraksti nesakritīs. Kā parādīts iepriekš, Express webhook maršrutā izmantojiet express.raw({ type: "application/json" }).

Vai vēl ir jautājumi?

Jautājumu gadījumā rakstiet mums uz support@feeder.co.