Вебхуки
За допомогою FastComments можна викликати кінцеву точку API щоразу, коли коментар додається, оновлюється або видаляється з нашої системи.
Ми реалізуємо це за допомогою асинхронних вебхуків через HTTP/HTTPS.
Що таке вебхуки 
Вебхук — це механізм або інтеграція між двома системами, де "виробник" (FastComments) ініціює подію яку "споживач" (Ви) обробляє через виклик API.
Підтримувані події та ресурси
FastComments підтримує вебхуки лише для ресурсу Comment.
Ми підтримуємо вебхуки для створення коментаря, видалення та оновлення.
Кожен із цих випадків вважається окремою подією в нашій системі і тому має різну семантику та структуру подій вебхука.
Налаштування локальної розробки
For Local development, use a tool like ngrok.
In order to simplify keeping the system secure, local development follows the same process as setting up and securing other environments.
Крок 1: Додайте "localhost" до доменів у вашому обліковому записі.
Add "localhost" as a domain here.
Крок 2: Виберіть API Key
We're going to be adding webhook configuration for your domain, so we'll need an API key. You can do that here.
Under "Associate with domain" - select your "localhost" domain.
ПРИМІТКА: Альтернативно, ви можете використовувати один API Secret для всіх тестових дій та середовищ підготовки. Просто додайте API Secret для "All Domains", і дайте йому назву, наприклад "test".
Ensure you have an API Secret defined for your production domain(s). Events for all other domains will use the wildcard (testing) secret.
Крок 3: Додайте ваш Webhook
While running ngrok or similar tool, set the value for "localhost" here.
When clicking Send Test Payload, we will send two test events to check that you validate the API key.
Once it validates, hit Save.
Крок 4: Додайте A Comment
Now you can add, edit, or delete comments and should see us call your local development machine with the events, using your testing API key. There may be up to 30 seconds delay for the events to reach your machine.
Налаштування
Follow the same steps for localhost as you would production. Ensure you have production domains and API Secrets setup.
First, navigate to the Адміністрування Webhooks. This is accessible via Manage Data -> Webhooks.
The configuration page appears as follows:
In this page you can specify endpoints for each type of comment event.
For each type of event, be sure to click Send Test Payload to ensure you've set up your integration correctly. See the next section, "Testing", for details.
Тестування
В адмінці 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
The "Create" Event Structure
Тіло запиту події "create" є об'єктом WebhookComment.
The "Update" Event Structure
Тіло запиту події "update" є об'єктом WebhookComment.
The "Delete" Event Structure
Тіло запиту події "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 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 або PUT (за замовчуванням: PUT)
- Update Event: POST або PUT (за замовчуванням: PUT)
- Delete Event: DELETE, POST, або PUT (за замовчуванням: DELETE)
Оскільки всі запити містять ID, операції Create та Update за замовчуванням ідемпотентні (PUT). Повторне надсилання того ж запиту Create або Update не має створювати дублікати об'єктів у вас.
Request Headers
Кожний запит вебхука містить такі заголовки:
| Header | Description |
|---|---|
Content-Type | application/json |
token | Ваш API Secret |
X-FastComments-Timestamp | Unix-мітка часу (секунди), коли запит було підписано |
X-FastComments-Signature | Підпис HMAC-SHA256 (sha256=<hex>) |
See Безпека та API токени for information on verifying the HMAC signature.
Безпека та API-токени
FastComments webhook requests include multiple authentication mechanisms for security.
Відправлені заголовки
| Заголовок | Опис |
|---|---|
token | Ваш API Secret (для зворотної сумісності) |
X-FastComments-Timestamp | Unix-часова мітка (секунди) коли запит був підписаний |
X-FastComments-Signature | HMAC-SHA256 підпис навантаження |
Перевірка підпису HMAC (рекомендовано)
Ми настійно рекомендуємо перевіряти підпис HMAC, щоб переконатися, що навантаження вебхука є автентичними і не були підроблені.
Формат підпису: sha256=<hex-encoded-signature>
Як обчислюється підпис:
- Конкатенувати:
timestamp + "." + JSON_payload_body - Обчислити HMAC-SHA256, використовуючи ваш API Secret як ключ
- Перетворити результат у шістнадцятковий формат
Приклад перевірки (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}`;
}Приклад перевірки (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}"Приклад перевірки (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);
}Спадкова автентифікація
Заголовок token, що містить ваш API Secret, все ще надсилається для зворотної сумісності. Однак ми рекомендуємо перейти на перевірку HMAC для підвищеної безпеки, оскільки вона захищає від повторних атак.
Як це працює та обробка повторних спроб
Усі зміни об'єкта Comment у системі викликають подію, яка потрапляє в чергу.
Початковий вебхук зазвичай надсилається протягом шести секунд після виникнення джерела події.
Ви можете відстежувати цю чергу в панелі адміністрування Webhooks на випадок, якщо ваш API вийде з ладу.
Якщо запит до вашого API не вдається, ми повторно помістимо його в чергу за певним графіком.
Цей графік — 1 Minute * the retry count. Якщо виклик не вдається один раз, він спробує ще раз через
хвилину. Якщо він не вдасться двічі, тоді зачекає дві хвилини, і так далі. Це зроблено для того, щоб ми
не перевантажували ваш API, якщо він виходить з ладу з причин, пов'язаних з навантаженням.
Вебхуки можна скасувати на сторінці журналу.
На завершення
Цим завершується наша документація Webhooks.
Ми сподіваємося, що інтеграція FastComments Webhook є зрозумілою та швидкою у налаштуванні.
Якщо ви вважаєте, що виявили будь-які прогалини в нашій документації, повідомте нас нижче.