Создание собственных интеграций с помощью вебхуков

Правило «Отправить на Webhook» позволяет автоматически отправлять новые публикации из RSS-лент на указанный вами адрес вебхука сразу после их появления. Можно также настроить фильтрацию публикаций по ключевым словам. Когда новая публикация соответствует заданным условиям, Feeder отправит её на ваш адрес вебхука в виде POST-запроса с данными в формате JSON.

Формат данных JSON

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

В запрос также включены метаданные для идентификации сообщения вебхука. Поле version указывает версию API вебхуков Feeder. Сейчас используется версия 2023-06-26. Она будет обновлена, если появятся несовместимые изменения.

{
  "version": "2023-06-26",
  "message_id": "уникальный UUID этого сообщения, не меняется при повторных попытках",
  "feed": { ... },
  "post": { ... }
}

Элемент post содержит информацию об отдельной публикации:

{
  "id": "уникальный идентификатор публикации",
  "title": "заголовок публикации",
  "url": "URL публикации",
  "published": "дата и время публикации",
  "content": "содержимое публикации",
  "audio_url": "ссылка на прикреплённый к публикации MP3-файл, если он есть",
  "image_url": "ссылка на прикреплённое к публикации изображение, если оно есть"
}

Примечание: значение published будет равно null, если в RSS-ленте не указана корректная дата публикации.

Элемент feed содержит информацию об источнике публикации:

{
  "id": "уникальный идентификатор ленты",
  "source_url": "URL источника, например RSS- или Atom-ленты",
  "public_url": "общедоступный URL источника, указанный самим источником",
  "title": "название ленты",
  "favicon": "URL значка ленты"
}

В будущем мы можем добавить новые поля в эти объекты. Если вам чего-то не хватает, сообщите нам.

Повторные попытки

Если запрос завершается ошибкой, 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. Чтобы проверить, правильно ли всё настроено, нажмите кнопку «Отправить тестовое сообщение». На ваш адрес будет отправлено тестовое уведомление. Обратите внимание: это только проверка, и если она завершится ошибкой, повторные попытки отправки не запустятся. Кроме того, для отправки тестового сообщения в аккаунте должна быть хотя бы одна лента с публикациями.

Безопасность: проверка подписей вебхуков

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

Как это работает

1. В настройках правила включите параметр «Расширенный». В поле «Секрет Webhook» появится строка.
2. Когда Feeder отправляет вебхук на ваш адрес, он вычисляет хеш 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();
}

// Важно: используйте express.raw(), чтобы req.body содержал исходную строку, а не разобранный JSON
app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  verifyFeederSignature,
  (req, res) => {
    const payload = JSON.parse(req.body);
    // Обработайте данные вебхука
    console.log("Получен проверенный вебхук:", payload);
    res.sendStatus(200);
  }
);

Важно: для проверки подписи необходимо получить исходное тело запроса. Если фреймворк разбирает JSON до вычисления HMAC, повторно сериализованная строка может отличаться от исходной, и подписи не совпадут. В Express укажите express.raw({ type: "application/json" }) для маршрута вебхука, как показано выше.

Остались вопросы?

Напишите нам по адресу support@feeder.co.