С FastComments можно вызывать API endpoint всякий раз, когда в нашей системе добавляется, обновляется или удаляется комментарий.
Мы осуществляем это с помощью asynchronous webhooks по протоколам HTTP/HTTPS.
Что такое вебхуки 
Вебхук — это механизм или интеграция между двумя системами, где "производитель" (FastComments) генерирует событие которое "потребитель" (Вы) обрабатывает посредством вызова API.
Поддерживаемые события и ресурсы
FastComments поддерживает вебхуки только для ресурса Comment.
Мы поддерживаем вебхуки при создании комментария, его удалении и обновлении.
Каждое из них считается отдельным событием в нашей системе и, как следствие, имеет разную семантику и структуру событий вебхуков.
Настройка локальной разработки
Для локальной разработки используйте инструмент вроде ngrok.
Чтобы упростить обеспечение безопасности системы, локальная разработка следует тому же процессу, что и настройка и защита других окружений.
Шаг 1: Добавьте "localhost" в домены в вашей учётной записи.
Добавьте "localhost" как домен здесь.
Шаг 2: Выберите API-ключ
Мы собираемся добавить конфигурацию вебхука для вашего домена, поэтому нам потребуется API-ключ. Вы можете сделать это здесь.
В поле "Associate with domain" - выберите ваш домен "localhost".
ПРИМЕЧАНИЕ: В качестве альтернативы вы можете использовать один API Secret для всей тестовой активности и окружений staging. Просто добавьте API Secret для "All Domains", и дайте ему имя, например "test".
Убедитесь, что у вас определён API Secret для ваших production-доменов. События для всех остальных доменов будут использовать wildcard (тестовый) секрет.
Шаг 3: Добавьте ваш вебхук
Во время запуска ngrok или аналогичного инструмента установите значение для "localhost" здесь.
При нажатии Send Test Payload, мы отправим два тестовых события, чтобы проверить, что вы валидируете API-ключ.
После подтверждения нажмите Save.
Шаг 4: Добавьте комментарий
Теперь вы можете добавлять, редактировать или удалять комментарии и должны увидеть, как мы вызываем вашу локальную машину разработки с событиями, используя ваш тестовый API-ключ. Может быть до 30 секунд задержки прежде чем события достигнут вашей машины.
Настройка
Выполните те же шаги для localhost, что и для production. Убедитесь, что у вас настроены production-домены и API Secrets.
Сначала перейдите в Webhooks admin. К этой странице можно добраться через Manage Data -> Webhooks.
Страница конфигурации выглядит следующим образом:
На этой странице вы можете указать конечные точки для каждого типа события комментария.
Для каждого типа события обязательно нажмите Send Test Payload, чтобы убедиться, что интеграция настроена правильно. Подробности — в следующем разделе «Тестирование».
Тестирование
В админке Webhooks есть кнопки Send Test Payload для каждого типа события (Create, Update, Delete). События Create и Update отправляют фиктивный объект WebhookComment, тогда как при тестировании Delete будет отправлено фиктивное тело запроса, содержащее только ID.
Проверка полезных нагрузок
При тестировании интеграции webhook убедитесь, что входящие запросы содержат следующие заголовки:
token- Ваш секрет APIX-FastComments-Timestamp- Метка времени Unix (в секундах)X-FastComments-Signature- Подпись HMAC-SHA256
Используйте проверку подписи HMAC, чтобы убедиться, что полезные нагрузки подлинны.
Инструменты для тестирования
Вы можете использовать такие инструменты, как webhook.site или ngrok, чтобы просматривать входящие полезные нагрузки вебхуков во время разработки.
Event Types
- Create Event: Срабатывает при создании нового комментария. Метод по умолчанию: PUT
- Update Event: Срабатывает при редактировании комментария. Метод по умолчанию: PUT
- Delete Event: Срабатывает при удалении комментария. Метод по умолчанию: DELETE
Каждое событие включает полный набор данных комментария в теле запроса (см. Структуры данных для формата полезной нагрузки).
Структуры данных
Единственная структура, отправляемая через вебхуки, — это объект WebhookComment, описанный на TypeScript ниже.
Структура объекта WebhookComment
Структура события «create»
Тело запроса для события «create» — объект WebhookComment.
Структура события «update»
Тело запроса для события «update» — объект WebhookComment.
Структура события «delete»
Тело запроса для события «delete» — объект WebhookComment.
Изменение с 14 ноября 2023 г.
Ранее тело запроса для события «delete» содержало только id комментария. Теперь оно содержит полный комментарий на момент удаления.
Run Когда в комментарии упоминают пользователей, информация хранится в списке mentions. Каждый объект в этом списке
имеет следующую структуру.
Run HTTP-методы
Вы можете настроить HTTP-метод для каждого типа события вебхука в панели администратора:
- Событие «create»: POST или PUT (по умолчанию: PUT)
- Событие «update»: POST или PUT (по умолчанию: PUT)
- Событие «delete»: DELETE, POST или PUT (по умолчанию: DELETE)
Поскольку все запросы содержат ID, операции Create и Update по умолчанию идемпотентны (PUT). Повторение того же запроса Create или Update не должно создавать дубликаты объектов на вашей стороне.
Заголовки запроса
Каждый запрос вебхука содержит следующие заголовки:
| Заголовок | Описание |
|---|---|
Content-Type |
application/json |
token |
Ваш секрет API |
X-FastComments-Timestamp |
Unix-временная метка (секунды), указывающая время подписи запроса |
X-FastComments-Signature |
Подпись HMAC-SHA256 (sha256=<hex>) |
См. Безопасность и API-токены для информации о проверке подписи HMAC.
Безопасность и API-токены
FastComments webhook requests include multiple authentication mechanisms for security.
Отправляемые заголовки
| Заголовок | Описание |
|---|---|
token |
Ваш API Secret (для обратной совместимости) |
X-FastComments-Timestamp |
Unix-временная метка (в секундах), когда запрос был подписан |
X-FastComments-Signature |
Подпись HMAC-SHA256 полезной нагрузки |
HMAC Signature Verification (Recommended)
Мы настоятельно рекомендуем проверять подпись HMAC, чтобы убедиться, что полезные данные webhook подлинны и не были изменены.
Signature Format: sha256=<hex-encoded-signature>
How the signature is computed:
- Объедините:
timestamp + "." + JSON_payload_body - Вычислите HMAC-SHA256, используя ваш API Secret в качестве ключа
- Преобразуйте результат в шестнадцатеричную строку
Example Verification (Node.js)
const crypto = require('crypto');
function verifyWebhookSignature(req, apiSecret) {
const timestamp = req.headers['x-fastcomments-timestamp'];
const signature = req.headers['x-fastcomments-signature'];
if (!timestamp || !signature) {
return false;
}
// Проверить, что метка времени недавняя (в пределах 5 минут)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
return false; // Предотвращение атак повторного воспроизведения
}
// Проверить подпись
const payload = JSON.stringify(req.body);
const expectedSignature = crypto
.createHmac('sha256', apiSecret)
.update(`${timestamp}.${payload}`)
.digest('hex');
return signature === `sha256=${expectedSignature}`;
}Example Verification (Python)
import hmac
import hashlib
import time
import json
def verify_webhook_signature(headers, body, api_secret):
timestamp = headers.get('X-FastComments-Timestamp')
signature = headers.get('X-FastComments-Signature')
if not timestamp or not signature:
return False
# Проверить, что метка времени недавняя
now = int(time.time())
if abs(now - int(timestamp)) > 300:
return False
# Проверить подпись
payload = json.dumps(body, separators=(',', ':'))
message = f"{timestamp}.{payload}"
expected = hmac.new(
api_secret.encode(),
message.encode(),
hashlib.sha256
).hexdigest()
return signature == f"sha256={expected}"Example Verification (PHP)
function verifyWebhookSignature($headers, $body, $apiSecret) {
$timestamp = $headers['X-FastComments-Timestamp'] ?? null;
$signature = $headers['X-FastComments-Signature'] ?? null;
if (!$timestamp || !$signature) {
return false;
}
// Проверить, что метка времени недавняя (в пределах 5 минут)
$now = time();
if (abs($now - intval($timestamp)) > 300) {
return false;
}
// Проверить подпись
$payload = json_encode($body, JSON_UNESCAPED_SLASHES);
$message = $timestamp . '.' . $payload;
$expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);
return hash_equals($expectedSignature, $signature);
}Legacy Authentication
Заголовок token, содержащий ваш API Secret, по-прежнему отправляется для обратной совместимости. Тем не менее, мы рекомендуем перейти на проверку HMAC для повышения безопасности, так как она защищает от атак повторного воспроизведения.
Как это работает и обработка повторных попыток
Все изменения объекта Comment в системе генерируют событие, которое попадает в очередь.
Первичное событие webhook обычно отправляется в течение шести секунд после возникновения исходного события.
Вы можете отслеживать эту очередь в Webhooks admin на случай, если ваш API выйдет из строя.
Если запрос к вашему API не удаётся, мы поставим его обратно в очередь по расписанию.
That schedule is 1 Minute * the retry count. Если вызов неудачен один раз, он попробует снова через
минуту. Если он потерпит неудачу дважды, он подождёт две минуты, и так далее. Это сделано для того, чтобы мы
не перегружали ваш API, если он выходит из строя по причинам, связанным с нагрузкой.
Webhooks можно отменить со страницы логов.
В заключение
На этом завершается наша документация по вебхукам.
Надеемся, что интеграция вебхуков FastComments понятна и проста в настройке.
Если вы считаете, что нашли пробелы в нашей документации, сообщите нам ниже.