Як створити власні інтеграції за допомогою вебхуків

The «Надіслати на Webhook» rule lets you automate sending new RSS feed posts to your specified webhook endpoint as soon as they become available. You can also fine-tune which posts are sent by setting up keywords to filter on. When a new post matches your criteria, it will be sent to your webhook endpoint as a JSON-formatted POST request.

Формат JSON-повідомлення

Кожен POST-запит, надісланий на ваш вебхук, містить два основні елементи: post і feed.

Також запит містить метадані для ідентифікації повідомлення вебхука. Поле version указує версію API вебхуків 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 хвилин

Зверніть увагу: механізм повторних спроб запускається лише для реальних подій із дописами й не застосовується до тестових сповіщень. Часові інтервали також можуть змінюватися.

Налагодження

Якщо виникають помилки, їх можна знайти в журналі запусків дії. Відкрийте правило, яке не працює, і натисніть «Відкрити журнал помилок».

Там ви побачите докладнішу інформацію про невдалі запити вебхука.

Налаштування вебхука

Щоб налаштувати вебхук:

1. Перейдіть на сторінку Правила.
2. Створіть правило.
3. Укажіть назву, стрічки та умови.
4. У розділі «Що має відбуватися?» виберіть «Надіслати на Webhook».
5. Введіть URL вебхука у відповідне текстове поле.
6. Щоб переконатися, що все налаштовано правильно, натисніть кнопку «Надіслати тестове повідомлення». Так ви надішлете тестове сповіщення на свій endpoint. Зверніть увагу: це лише тест, і якщо він завершиться помилкою, механізм повторних спроб не запуститься. Щоб надіслати тестовий допис, у вашому обліковому записі має бути принаймні одна стрічка з доданими дописами.

Безпека: перевірка підписів вебхуків

Щоб переконатися, що вхідні запити вебхуків справді надійшли від Feeder і їх не було змінено, перевірте секретний ключ вебхука, створений для кожного вебхука. Кожен запит вебхука міститиме заголовок X-Feeder-Signature із підписом тіла запиту, створеним за допомогою HMAC-SHA256.

Як це працює

1. У налаштуваннях правила ввімкніть параметр «Розширені». У полі «Webhook Secret» ви побачите рядок.
2. Коли Feeder надсилає вебхук на ваш 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" }) для маршруту вебхука, як показано вище.

Є запитання?

Напишіть нам на support@feeder.co.