Създаване на собствени интеграции с Webhook

Правилото „Публикувай в Webhook“ автоматизира изпращането на нови публикации от RSS емисии до зададен от вас webhook endpoint веднага щом се появят. Можете също да зададете ключови думи, за да филтрирате публикациите, които се изпращат. Когато нова публикация отговаря на критериите ви, тя ще бъде изпратена до webhook endpoint като POST заявка във формат JSON.

Формат на JSON данните

Всяка POST заявка, изпратена до вашия webhook, съдържа два основни елемента: post и feed.

Заявката съдържа и метаданни, с които се идентифицира съобщението на webhook. Полето version посочва версията на API за webhook на Feeder, която се използва. Версията винаги е 2023-06-26 и ще бъде актуализирана при промени, които нарушават обратната съвместимост.

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

Елементът 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)
}

Забележка: published ще има стойност null, ако RSS емисията не съдържа валидна дата на публикуване.

Елементът feed съдържа информация за емисията, от която е публикацията:

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

Възможно е в бъдеще да добавим полета към тези обекти. Ако ви липсва нещо, уведомете ни.

Повторни опити

Ако заявката е неуспешна, Feeder автоматично опитва да я изпрати отново. Ако POST заявката не получи HTTP код за отговор от 200 до 399, ще направим нов опит по следния график, зададен в секунди:

• Опит 1: след 5 секунди
• Опит 2: след 30 секунди
• Опит 3: след 60 секунди
• Опит 4: след 5 минути
• Опит 5: след 10 минути
• Опит 6: след 30 минути
• Опит 7: след 30 минути
• Опит 8: след 30 минути

Имайте предвид, че механизмът за повторни опити се задейства само при реални събития, свързани с публикации, и не важи за тестовите известия. Интервалите също може да се променят.

Отстраняване на проблеми

Ако възникнат грешки, можете да ги намерите в журнала с изпълненията на действията. Отворете правилото, което не работи, и натиснете „Отвори журнала с грешки“.

Там ще видите повече подробности за неуспешните webhook заявки.

Настройване на webhook

За да настроите webhook:

1. Отворете страницата Правила.
2. Създайте ново правило.
3. Добавете име, емисии и критерии.
4. В секцията „Какво трябва да се случи?“ изберете „Публикувай в Webhook“.
5. Въведете URL адреса на webhook в съответното текстово поле.
6. За да проверите дали всичко е настроено правилно, натиснете бутона „Изпрати тестово съобщение“, за да изпратите тестово известие до endpoint. Имайте предвид, че това е само тест и при неуспех няма да задейства механизма за повторни опити. За да бъде изпратена тестова публикация, трябва да имате поне 1 емисия с добавени към нея публикации в акаунта си.

Сигурност: проверка на подписите на webhook заявките

За да проверите дали входящите webhook заявки действително са от Feeder и не са били подправени, можете да проверите тайната за webhook, която се генерира за всеки webhook. Всяка webhook заявка включва заглавка X-Feeder-Signature с подпис HMAC-SHA256 на тялото на заявката.

Как работи

1. В настройките на правилото включете опцията „Разширени“. В полето „Тайна за webhook“ ще видите низ от символи.
2. Когато Feeder изпраща webhook заявка до вашия endpoint, изчислява хеш HMAC-SHA256 на тялото на JSON заявката, като използва вашата тайна като ключ.
3. Полученият подпис се изпраща в заглавката X-Feeder-Signature с префикс sha256=. Например:

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

4. На сървъра си изчислете отново същия хеш HMAC-SHA256, като използвате суровото тяло на заявката и вашето копие на тайната. След това сравнете резултата със стойността в заглавката.

Защо да използвате тази проверка?

• Автентичност: потвърждава, че заявката е изпратена от Feeder, а не от трета страна.
• Цялостност: гарантира, че данните не са били променени по време на преноса.

Проверка на подписа

За да проверите подписа:

1. Прочетете суровото тяло на заявката като низ, без първо да го парсвате.
2. Изчислете HMAC-SHA256 на този низ, като използвате тайната си.
3. Сравнете изчисления от вас подпис със стойността в заглавката X-Feeder-Signature, като използвате сравнение, защитено от атаки по времето за изпълнение, за да предотвратите атаки по времето.

Пример: 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);
  }
);

Важно: За проверката на подписа трябва да използвате суровото тяло на заявката. Ако рамката ви парсне JSON тялото, преди да изчислите HMAC, повторно сериализираният низ може да се различава от оригинала и подписът няма да съвпадне. В Express използвайте express.raw({ type: "application/json" }) за webhook маршрута, както е показано по-горе.

Имате ли други въпроси?

Имате въпроси? Пишете ни на support@feeder.co.