Webhooki
Z FastComments możliwe jest wywołanie punktu końcowego API za każdym razem, gdy komentarz zostanie dodany, zaktualizowany lub usunięty z naszego systemu.
Realizujemy to za pomocą asynchronicznych webhooków przez HTTP/HTTPS.
Czym są webhooki 
Webhook to mechanizm, lub integracja, pomiędzy dwoma systemami gdzie "producent" (FastComments) wyzwala zdarzenie które "konsument" (Ty) odbiera za pomocą wywołania API.
Obsługiwane zdarzenia i zasoby
FastComments obsługuje webhooki tylko dla zasobu Comment.
Obsługujemy webhooki dla tworzenia komentarza, usuwania oraz aktualizacji.
Każde z nich jest w naszym systemie traktowane jako odrębne zdarzenie i w związku z tym ma inną semantykę i inną strukturę zdarzeń webhook.
Konfiguracja środowiska lokalnego
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.
Krok 1: Dodaj „localhost” do domen w swoim koncie.
Add "localhost" as a domain here.
Krok 2: Wybierz klucz API
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.
UWAGA: Alternatywnie możesz używać jednego tajnego klucza API dla całej aktywności testowej i środowisk staging. Po prostu dodaj tajny klucz API dla "All Domains", i nadaj mu nazwę, np. "test".
Ensure you have an API Secret defined for your production domain(s). Events for all other domains will use the wildcard (testing) secret.
Krok 3: Dodaj swój 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.
Krok 4: Dodaj komentarz
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.
Konfiguracja
Follow the same steps for localhost as you would production. Ensure you have production domains and API Secrets setup.
First, navigate to the panelu administracyjnego webhooków. This is accessible via Manage Data -> Webhooki.
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, „Testowanie”, for details.
Testowanie
W panelu administracyjnym Webhooks znajdują się przyciski Send Test Payload dla każdego typu zdarzenia (Create, Update, Delete). Zdarzenia Create i Update wysyłają przykładowy obiekt WebhookComment, natomiast testowanie Delete wyśle przykładowe ciało żądania zawierające tylko identyfikator.
Weryfikacja ładunków
Podczas testowania integracji webhook sprawdź, czy przychodzące żądania zawierają następujące nagłówki:
token- Twój sekret APIX-FastComments-Timestamp- znacznik czasu Unix (sekundy)X-FastComments-Signature- podpis HMAC-SHA256
Użyj weryfikacji podpisu HMAC, aby upewnić się, że ładunki są autentyczne.
Narzędzia do testowania
Możesz użyć narzędzi takich jak webhook.site lub ngrok, aby sprawdzać przychodzące ładunki webhooków podczas tworzenia.
Typy zdarzeń
- Create Event: Wywoływane, gdy zostanie utworzony nowy komentarz. Domyślna metoda: PUT
- Update Event: Wywoływane, gdy komentarz zostanie edytowany. Domyślna metoda: PUT
- Delete Event: Wywoływane, gdy komentarz zostanie usunięty. Domyślna metoda: DELETE
Każde zdarzenie zawiera pełne dane komentarza w ciele żądania (zobacz Struktury danych dla formatu ładunku).
Struktury danych
Jedynej struktury wysyłanej przez webhooks jest obiekt WebhookComment, opisany poniżej w TypeScript.
Struktura obiektu WebhookComment
Struktura zdarzenia "create"
Ciało żądania zdarzenia "create" to obiekt WebhookComment.
Struktura zdarzenia "update"
Ciało żądania zdarzenia "update" to obiekt WebhookComment.
Struktura zdarzenia "delete"
Ciało żądania zdarzenia "delete" to obiekt WebhookComment.
Zmiana od 14 listopada 2023
Wcześniej ciało żądania zdarzenia "delete" zawierało tylko id komentarza. Teraz zawiera pełny komentarz w momencie usunięcia.
Run Gdy użytkownicy są oznaczani w komentarzu, informacja jest przechowywana na liście o nazwie mentions. Każdy obiekt na tej liście ma następującą strukturę.
Run Metody HTTP
Możesz skonfigurować metodę HTTP dla każdego typu zdarzenia webhook w panelu administracyjnym:
- Create Event: POST lub PUT (domyślnie: PUT)
- Update Event: POST lub PUT (domyślnie: PUT)
- Delete Event: DELETE, POST lub PUT (domyślnie: DELETE)
Ponieważ wszystkie żądania zawierają ID, operacje Create i Update są domyślnie idempotentne (PUT). Powtarzanie tego samego żądania Create lub Update nie powinno tworzyć duplikatów po Twojej stronie.
Nagłówki żądań
Każde żądanie webhook zawiera następujące nagłówki:
| Header | Description |
|---|---|
Content-Type | application/json |
token | Twój sekret API |
X-FastComments-Timestamp | Znacznik czasu Unix (sekundy) w momencie podpisania żądania |
X-FastComments-Signature | Podpis HMAC-SHA256 (sha256=<hex>) |
Zobacz Security & API Tokens aby uzyskać informacje o weryfikacji podpisu HMAC.
Bezpieczeństwo i tokeny API
FastComments webhook requests include multiple authentication mechanisms for security.
Wysyłane nagłówki
| Nagłówek | Opis |
|---|---|
token | Twój API Secret (w celu zachowania zgodności wstecznej) |
X-FastComments-Timestamp | Znacznik czasu Unix (sekundy), kiedy żądanie zostało podpisane |
X-FastComments-Signature | Podpis HMAC-SHA256 ładunku |
Weryfikacja podpisu HMAC (zalecane)
Zdecydowanie zalecamy weryfikację podpisu HMAC, aby upewnić się, że ładunki webhooków są autentyczne i nie zostały zmienione.
Format podpisu: sha256=<hex-encoded-signature>
Jak obliczany jest podpis:
- Połącz:
timestamp + "." + JSON_payload_body - Oblicz HMAC-SHA256 używając swojego API Secret jako klucza
- Zakoduj wynik w hex
Przykład weryfikacji (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;
}
// Zweryfikuj, że znacznik czasu jest aktualny (w ciągu 5 minut)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
return false; // Zapobieganie atakom powtórzeniowym
}
// Verify signature
const payload = JSON.stringify(req.body);
const expectedSignature = crypto
.createHmac('sha256', apiSecret)
.update(`${timestamp}.${payload}`)
.digest('hex');
return signature === `sha256=${expectedSignature}`;
}Przykład weryfikacji (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
# Zweryfikuj, że znacznik czasu jest aktualny
now = int(time.time())
if abs(now - int(timestamp)) > 300:
return False
# Zweryfikuj podpis
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}"Przykład weryfikacji (PHP)
function verifyWebhookSignature($headers, $body, $apiSecret) {
$timestamp = $headers['X-FastComments-Timestamp'] ?? null;
$signature = $headers['X-FastComments-Signature'] ?? null;
if (!$timestamp || !$signature) {
return false;
}
// Zweryfikuj, że znacznik czasu jest aktualny (w ciągu 5 minut)
$now = time();
if (abs($now - intval($timestamp)) > 300) {
return false;
}
// Zweryfikuj podpis
$payload = json_encode($body, JSON_UNESCAPED_SLASHES);
$message = $timestamp . '.' . $payload;
$expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);
return hash_equals($expectedSignature, $signature);
}Starsze uwierzytelnianie
Nagłówek token zawierający Twój API Secret wciąż jest wysyłany dla zachowania zgodności wstecznej. Jednak zalecamy przejście na weryfikację HMAC dla lepszego bezpieczeństwa, ponieważ chroni ona przed atakami powtórzeniowymi.
Jak to działa i obsługa ponownych prób
Wszystkie zmiany obiektu Comment w systemie wywołują zdarzenie, które trafia do kolejki.
Początkowe zdarzenie webhook jest zwykle wysyłane w ciągu sześciu sekund od wystąpienia źródła zdarzenia.
Możesz monitorować tę kolejkę w panelu administracyjnym Webhooks na wypadek, gdyby Twoje API przestało działać.
Jeśli żądanie do Twojego API się nie powiedzie, ponownie umieścimy je w kolejce zgodnie z harmonogramem.
Ten harmonogram to 1 Minute * the retry count. Jeśli wywołanie zakończy się niepowodzeniem raz, spróbuje ponownie za
minutę. Jeśli nie powiedzie się dwa razy, poczeka wtedy dwie minuty, i tak dalej. Dzięki temu
nie przeciążymy Twojego API, jeśli przestaje działać z powodów związanych z obciążeniem.
Webhooks można anulować z strony logów.
Podsumowanie
To kończy naszą dokumentację Webhooks.
Mamy nadzieję, że integracja FastComments Webhook jest łatwa do zrozumienia i szybka do skonfigurowania.
Jeśli uważasz, że zidentyfikowałeś jakiekolwiek luki w naszej dokumentacji, daj nam znać poniżej.