Sat Sep 26 2020
...

Webhooks приходят в FastComments

! Эта статья содержит техническую терминологию

Что нового

С FastComments теперь возможно вызывать API-эндпоинт всякий раз, когда комментарий добавляется, обновляется или удаляется из нашей системы.

Мы осуществляем это с помощью асинхронных вебхуков через HTTP/HTTPS.

Как это использовать

Сначала перейдите в админку вебхуков. Это доступно через Управление данными -> Вебхуки.

Оттуда вы можете указать эндпоинты для каждого типа события комментария.

Для каждого типа события обязательно нажмите Отправить тестовую нагрузку, чтобы убедиться, что вы правильно настроили вашу интеграцию. Смотрите следующий раздел "Тестирование" для подробностей.

Тестирование

В админке вебхуков имеются кнопки "Отправить тестовую нагрузку" для каждого типа события (Создание, Обновление, Удаление). События Создание и Обновление отправляют объект WebhookComment, в то время как тестирование Удаления отправляет тело запроса с только ID.

Тест сделает два вызова, чтобы проверить код ответа для "счастливого" (корректный API ключ) и "печального" (некорректный API ключ) сценариев.

Когда тест отправляет некорректный API ключ, вы должны вернуть код состояния 401, чтобы тест полностью прошел. Если вы не проверите значение токена правильно, вы увидите ошибку, похожую на:

Структура объекта комментария

/** * @typedef {Object} WebhookComment * @property {string} id * @property {string} urlId * @property {string} url * @property {string} userId * @property {string} commenterEmail * @property {string} commenterName * @property {string} comment * @property {string} commentHTML * @property {string} parentId * @property {DateString} date * @property {number} votes * @property {boolean} verified * @property {number} verifiedDate * @property {boolean} reviewed * @property {string} avatarSrc * @property {boolean} isSpam * @property {boolean} aiDeterminedSpam * @property {boolean} hasImages * @property {number} pageNumber * @property {boolean} approved * @property {string} locale */

Структура события "Создать"

Тело запроса события "создать" — это объект WebhookComment.

Структура события "Обновить"

Тело запроса события "обновить" — это объект WebhookComment.

Структура события "Удалить"

Тело запроса события "удалить" — это объект WebhookComment, но содержащий только id.

Почему Создание и Обновление используют HTTP PUT, а не POST?

Поскольку все наши запросы содержат ID, повторение того же запроса Создания или Обновления не должно создавать новые объекты на вашей стороне. Это означает, что эти вызовы идемпотентны и должны быть событиями PUT в соответствии со спецификацией HTTP.

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

Все изменения в объекте комментария в системе вызывают событие, которое попадает в очередь. Вы можете отслеживать эту очередь в админке вебхуков на случай, если ваш API перестанет работать. Если запрос к вашему API не сработает, мы поставим его в очередь снова по расписанию. Это расписание — 1 минута * количество повторных попыток. Если вызов не сработает один раз, он попробует снова через минуту. Если он не сработает дважды, он подождет две минуты и так далее. Это нам необходимо, чтобы не перегружать ваш API, если он зависает по причине нагрузки.

Безопасность и токен API

В заголовке запроса мы передадим ваш API Secret в параметре под названием "token".

Если вы не проверите этот параметр должным образом, ваша интеграция не будет отмечена как Проверенная. Это мера безопасности для обеспечения того, чтобы любая интеграция с FastComments была безопасной.

В заключение

Мы надеемся, что интеграция с вебхуками FastComments окажется для вас простой и быстрой для настройки.

Если у вас есть дополнительные вопросы, не стесняйтесь обращаться на страницу поддержки клиентов.

Удачи!

Sat Sep 26 2020...