С FastComments можно вызывать конечную точку API всякий раз, когда комментарий добавляется, обновляется или удаляется в нашей системе.
Мы реализуем это с помощью асинхронных вебхуков по протоколам HTTP/HTTPS.
Что такое вебхуки 
Вебхук — это механизм, или интеграция, между двумя системами, где "производитель" (FastComments) генерирует событие которое "потребитель" (Вы) получает посредством вызова API.
Поддерживаемые события и ресурсы
FastComments поддерживает вебхуки только для ресурса Comment.
Мы поддерживаем вебхуки для создания, удаления и обновления комментариев.
Каждое из них в нашей системе считается отдельным событием и, соответственно, имеет различную семантику и структуру для событий вебхука.
Настройка локальной разработки
Для локальной разработки используйте инструмент вроде ngrok.
Чтобы упростить поддержание безопасности системы, локальная разработка следует тому же процессу, что и настройка и защита других окружений.
Шаг 1: Добавьте "localhost" в домены в вашей учётной записи.
Добавьте "localhost" как домен здесь.
Шаг 2: Выберите API Key
Мы будем добавлять конфигурацию webhook для вашего домена, поэтому нам понадобится API key. Вы можете сделать это здесь.
В поле "Associate with domain" — выберите ваш домен "localhost".
ПРИМЕЧАНИЕ: Альтернативно, вы можете использовать один API Secret для всей тестовой активности и окружений staging. Просто добавьте API Secret для "All Domains" и дайте ему имя вроде "test".
Убедитесь, что у вас определён API Secret для ваших production доменов. События для всех остальных доменов будут использовать универсальный (тестовый) секрет.
Шаг 3: Добавьте ваш Webhook
Во время работы ngrok или похожего инструмента установите значение для "localhost" здесь.
При нажатии Send Test Payload мы отправим два тестовых события, чтобы проверить, что вы валидируете API key.
После успешной валидации нажмите Save.
Шаг 4: Добавьте комментарий
Теперь вы можете добавлять, редактировать или удалять комментарии и должны увидеть, как мы вызываем вашу локальную машину разработки с событиями, используя ваш тестовый API key. Может пройти до 30 секунд задержки для того, чтобы события дошли до вашей машины.
Настройка
Выполните те же шаги для localhost, что и для production. Убедитесь, что у вас настроены production domains и API Secrets.
Сначала перейдите в Webhooks admin. Это доступно через Manage Data -> Webhooks.
Страница конфигурации выглядит следующим образом:
На этой странице вы можете указать endpoints для каждого типа событий комментариев.
Для каждого типа события обязательно нажимайте Send Test Payload, чтобы убедиться, что интеграция настроена правильно. Подробности см. в следующем разделе "Testing".
Тестирование
В админке Webhooks есть кнопки Send Test Payload для каждого типа события (Create, Update, Delete). События Create и Update отправляют тестовый объект WebhookComment, а при тестировании Delete отправляется тестовое тело запроса, содержащее только ID.
Проверка полезной нагрузки
При тестировании интеграции вебхуков убедитесь, что входящие запросы содержат следующие заголовки:
token- Ваш секрет APIX-FastComments-Timestamp- метка времени Unix (в секундах)X-FastComments-Signature- подпись HMAC-SHA256
Используйте проверку подписи HMAC, чтобы убедиться, что полезные нагрузки подлинные.
Инструменты тестирования
Вы можете использовать такие инструменты, как webhook.site или ngrok, чтобы просматривать входящие полезные нагрузки вебхуков во время разработки.
Типы событий
- Create Event: Вызывается при создании нового комментария. Метод по умолчанию: PUT
- Update Event: Вызывается при редактировании комментария. Метод по умолчанию: PUT
- Delete Event: Вызывается при удалении комментария. Метод по умолчанию: DELETE
Каждое событие включает полные данные комментария в теле запроса (см. Структуры данных для формата полезной нагрузки).
Структуры данных
Единственная структура, отправляемая через вебхуки, — это объект WebhookComment, описанный ниже на TypeScript.
Структура объекта WebhookComment
Структура события "Create"
Тело запроса для события "create" — это объект WebhookComment.
Структура события "Update"
Тело запроса для события "update" — это объект WebhookComment.
Структура события "Delete"
Тело запроса для события "delete" — это объект WebhookComment.
Change as of Nov 14th 2023
Previously the "delete" event request body only contained the comment id. It now contains the full comment at the time of deletion.
Run Когда пользователи отмечены в комментарии, информация хранится в списке с именем mentions. Каждый объект в этом списке имеет следующую структуру.
Run HTTP-методы
Вы можете настроить HTTP-метод для каждого типа события вебхука в панели администратора:
- Create Event: POST или PUT (по умолчанию: PUT)
- Update Event: POST или PUT (по умолчанию: PUT)
- Delete Event: 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>) |
См. Security & API Tokens для информации о проверке подписи HMAC.
Безопасность и API-токены
Запросы вебхуков FastComments включают несколько механизмов аутентификации для безопасности.
Headers Sent
| Header | Description |
|---|---|
token |
Ваш API Secret (для обратной совместимости) |
X-FastComments-Timestamp |
Unix-временная метка (в секундах), когда запрос был подписан |
X-FastComments-Signature |
HMAC-SHA256 подпись полезной нагрузки |
HMAC Signature Verification (Recommended)
Мы настоятельно рекомендуем проверять HMAC-подпись, чтобы убедиться, что полезные данные вебхука подлинны и не были изменены.
Signature Format: sha256=<hex-encoded-signature>
How the signature is computed:
- Concatenate:
timestamp + "." + JSON_payload_body - Compute HMAC-SHA256 using your API Secret as the key
- Hex-encode the result
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; // Защита от повторного воспроизведения (replay-атаки)
}
// Проверка подписи
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
The token header containing your API Secret is still sent for backwards compatibility. However, we recommend migrating to HMAC verification for improved security as it protects against replay attacks.
Как это работает и обработка повторных попыток
Все изменения объекта Comment в системе вызывают событие, которое попадает в очередь.
Изначальное событие вебхука обычно отправляется в течение шести секунд после возникновения источника события.
Вы можете отслеживать эту очередь в админ-панели Webhooks на случай, если ваш API выйдет из строя.
Если запрос к вашему API не удаётся, мы повторно поставим его в очередь по расписанию.
Это расписание — 1 Minute * the retry count. Если вызов не удастся один раз, запрос будет повторён через минуту. Если он не сработает дважды, повторная попытка будет через две минуты, и так далее. Это делается, чтобы не перегружать ваш API, если он выходит из строя по причинам, связанным с нагрузкой.
Webhooks можно отменить на странице журналов.
В заключение
На этом завершается наша документация по Webhooks.
Мы надеемся, что интеграция FastComments Webhook окажется понятной и быстрой в настройке.
Если вы считаете, что обнаружили какие-либо пробелы в нашей документации, сообщите нам об этом ниже.