С 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 admin есть кнопки Send Test Payload для каждого типа события (Create, Update, Delete). События Create и Update отправляют тестовый объект WebhookComment, тогда как при тестировании Delete будет отправлено тестовое тело запроса, содержащее только ID.
Проверка полезной нагрузки
При тестировании интеграции вебхуков убедитесь, что входящие запросы содержат следующие заголовки:
token- Your API SecretX-FastComments-Timestamp- Unix timestamp (seconds)X-FastComments-Signature- HMAC-SHA256 signature
Используйте проверку HMAC-подписи, чтобы убедиться в подлинности полезных нагрузок.
Инструменты тестирования
Вы можете использовать такие инструменты, как webhook.site или ngrok для просмотра входящих полезных нагрузок вебхуков во время разработки.
Типы событий
- Create Event: Вызывается при создании нового комментария. Метод по умолчанию: PUT
- Update Event: Вызывается при редактировании комментария. Метод по умолчанию: PUT
- Delete Event: Вызывается при удалении комментария. Метод по умолчанию: DELETE
Каждое событие включает полные данные комментария в теле запроса (см. Структуры данных для формата полезной нагрузки).
Структуры данных
Единственная структура, отправляемая через вебхуки — это объект WebhookComment, приведённый ниже на TypeScript.
Структура объекта WebhookComment
The "Create" Event Structure
Тело запроса события "create" — объект WebhookComment.
The "Update" Event Structure
Тело запроса события "update" — объект WebhookComment.
The "Delete" Event Structure
Тело запроса события "delete" — объект WebhookComment.
Изменение от 14 ноября 2023 г.
Ранее тело запроса события "delete" содержало только id комментария. Теперь оно содержит полный комментарий на момент удаления.
Run When users are tagged in a comment, the information is stored in a list called mentions. Each object in that list
has the following structure.
Run HTTP Methods
Вы можете настроить HTTP-метод для каждого типа события вебхука в панели администратора:
- Create Event: POST or PUT (default: PUT)
- Update Event: POST or PUT (default: PUT)
- Delete Event: DELETE, POST, or PUT (default: DELETE)
Поскольку все запросы содержат ID, операции Create и Update по умолчанию идемпотентны (PUT). Повторение того же запроса Create или Update не должно создавать дубликаты объектов на вашей стороне.
Request Headers
Каждый запрос вебхука содержит следующие заголовки:
| Header | Description |
|---|---|
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 понятна и проста в настройке.
Если вы считаете, что нашли пробелы в нашей документации, сообщите нам ниже.