С FastComments е възможно да се извика API endpoint всеки път, когато коментар бъде добавен, актуализиран или премахнат от нашата система.
Постигаме това с помощта на асинхронни webhooks по HTTP/HTTPS.
Какво представляват уебхуковете 
Уебхук е механизъм, или интеграция, между две системи, при която "произвеждащият" (FastComments) изпраща събитие което "потребителят" (Вие) обработва чрез API повикване.
Поддържани събития и ресурси
FastComments поддържа уебхукове само за ресурса Comment.
Поддържаме уебхукове при създаване, премахване и при актуализация на коментари.
Всяко от тях се разглежда като отделно събитие в нашата система и поради това има различна семантика и различна структура за събитията на уебхуковете.
Настройка за локална разработка
За локална разработка използвайте инструмент като ngrok.
За да опростите поддържането на сигурността на системата, локалната разработка следва същия процес като настройването и защитаването на другите среди.
Стъпка 1: Добавете "localhost" към домейните в акаунта си.
Добавете "localhost" като домейн тук.
Стъпка 2: Изберете API ключ
Ще добавим конфигурация за webhook за вашия домейн, затова ще ни трябва API ключ. Можете да го направите тук.
Under "Associate with domain" - select your "localhost" domain.
NOTE: Alternatively, you can use one API Secret for all testing activity and staging environments. Simply add an API Secret for "All Domains", and give it a name like "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
Докато работи ngrok или подобен инструмент, задайте стойността за "localhost" тук.
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: Добавете коментар
Сега можете да добавяте, редактирате или изтривате коментари и би трябвало да видите повиквания към вашата локална машина за разработка със събитията, използвайки вашия тестов API ключ. Може да има до 30 секунди забавяне за да достигнат събитията до вашата машина.
Настройка
Следвайте същите стъпки за localhost както бихте направили за production. Уверете се, че сте настроили production домейни и API Secrets.
Първо, отидете на Администриране на Webhooks. Това е достъпно чрез Manage Data -> Webhooks.
Страницата за конфигурация изглежда по следния начин:
На тази страница можете да посочите endpoints за всеки тип събитие на коментар.
За всеки тип събитие задължително кликнете върху Send Test Payload, за да се уверите, че интеграцията е настроена правилно. Вижте следващия раздел, "Testing", за подробности.
Тестване
В админ панела за Webhooks има бутони Send Test Payload за всеки тип събитие (Create, Update, Delete). Събитията Create и Update изпращат фиктивен обект WebhookComment, докато при тест на Delete ще бъде изпратено фиктивно тяло на заявката, съдържащо само ID.
Проверка на payload-ите
Когато тествате интеграцията на вашия webhook, уверете се, че входящите заявки включват следните заглавки:
token- Your API SecretX-FastComments-Timestamp- Unix timestamp (seconds)X-FastComments-Signature- HMAC-SHA256 signature
Използвайте проверката на HMAC подписа, за да се уверите, че payload-ите са автентични.
Инструменти за тестване
Можете да използвате инструменти като webhook.site или ngrok за да инспектирате входящите webhook payload-ове по време на разработка.
Типове събития
- Create Event: Се задейства, когато е създаден нов коментар. По подразбиране метод: PUT
- Update Event: Се задейства, когато коментарът бъде редактиран. По подразбиране метод: PUT
- Delete Event: Се задейства, когато коментарът бъде изтрит. По подразбиране метод: DELETE
Всяко събитие включва пълните данни на коментара в тялото на заявката (виж Структури от данни за формата на payload-а).
Структури от данни
Единствената структура, изпращана чрез уебхукове, е обектът WebhookComment, описан в TypeScript по-долу.
Структура на обекта WebhookComment
Структура за събитие "Create"
Тялото на заявката за събитие "create" е обект WebhookComment.
Структура за събитие "Update"
Тялото на заявката за събитие "update" е обект WebhookComment.
Структура за събитие "Delete"
Тялото на заявката за събитие "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
Всяка уебхук заявка включва следните хедъри:
| Заглавка | Описание |
|---|---|
Content-Type |
application/json |
token |
Your API Secret |
X-FastComments-Timestamp |
Unix timestamp (seconds) when the request was signed |
X-FastComments-Signature |
HMAC-SHA256 signature (sha256=<hex>) |
Вижте Сигурност и API токени за информация относно проверката на HMAC подписа.
Сигурност и API токени
FastComments webhook requests include multiple authentication mechanisms for security.
Изпращани заглавки
| Header | Description |
|---|---|
token |
Вашият API Secret (за обратна съвместимост) |
X-FastComments-Timestamp |
Unix времеви печат (в секунди), когато заявката е била подписана |
X-FastComments-Signature |
HMAC-SHA256 подпис на полезното съдържание |
HMAC Signature Verification (Recommended)
Силно препоръчваме да проверявате HMAC подписа, за да се уверите, че payload-ите на webhook-ите са автентични и не са били подправяни.
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);
}Наследствено удостоверяване
Хедърът token, съдържащ вашия API Secret, все още се изпраща за обратна съвместимост. Въпреки това препоръчваме миграция към проверка на HMAC за по-добра сигурност, тъй като тя предпазва от replay атаки.
Как работи и обработка на повторни опити
Всички промени в обекта Comment в системата предизвикват събитие, което се поставя в опашка.
Първоначалното webhook събитие обикновено се изпраща в рамките на шест секунди след настъпване на източника на събитието.
Можете да наблюдавате тази опашка в администрацията на Webhooks в случай че вашето API спре да работи.
Ако заявка към вашето API не успее, ние ще я поставим отново в опашката по график.
Този график е 1 Minute * the retry count. Ако повикването не успее веднъж, ще опита отново след една минута. Ако не успее два пъти, ще изчака две минути и т.н. Това е така, за да не претоварваме вашето API, ако то спре да работи по причини, свързани с натоварване.
Webhooks могат да бъдат отменени от страницата с логове.
В заключение
Това завършва нашата документация за Webhooks.
Надяваме се, че интеграцията на FastComments Webhook е лесна за разбиране и бърза за настройване.
Ако смятате, че сте открили пропуски в нашата документация, уведомете ни по-долу.