Mit FastComments ist es möglich, einen API-Endpunkt aufzurufen, wann immer ein Kommentar in unserem System hinzugefügt, aktualisiert oder entfernt wird.
Wir realisieren dies mit asynchronen Webhooks über HTTP/HTTPS.
Was sind Webhooks 
Ein Webhook ist ein Mechanismus oder eine Integration zwischen zwei Systemen, bei dem der "Produzent" (FastComments) ein Ereignis auslöst das der "Konsument" (Sie) per API-Aufruf verarbeitet.
Unterstützte Ereignisse und Ressourcen
FastComments unterstützt Webhooks nur für die Kommentar-Ressource.
Wir unterstützen Webhooks für die Erstellung, Entfernung und Aktualisierung von Kommentaren.
Jedes davon wird in unserem System als separates Ereignis betrachtet und hat daher unterschiedliche Semantik und Strukturen für die Webhook-Ereignisse.
Einrichtung der lokalen Entwicklungsumgebung
Für die lokale Entwicklung verwenden Sie ein Tool wie ngrok.
Um die Sicherheit des Systems zu vereinfachen, folgt die lokale Entwicklung demselben Prozess wie das Einrichten und Sichern anderer Umgebungen.
Step 1: Add "localhost" to domains in your account.
Fügen Sie "localhost" als Domain hier hinzu.
Step 2: Pick an API Key
Wir werden die Webhook-Konfiguration für Ihre Domain hinzufügen, daher benötigen wir einen API Key. Das können Sie hier tun.
Unter "Associate with domain" - wählen Sie Ihre "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".
Stellen Sie sicher, dass Sie ein API Secret für Ihre Produktionsdomain(s) definiert haben. Ereignisse für alle anderen Domains werden das Wildcard-(Testing-)Secret verwenden.
Step 3: Add Your Webhook
Während ngrok oder ein ähnliches Tool läuft, setzen Sie den Wert für "localhost" hier.
Beim Klicken auf Send Test Payload senden wir zwei Testereignisse, um zu überprüfen, dass Sie den API Key validieren.
Sobald dies validiert ist, klicken Sie auf Save.
Step 4: Add A Comment
Jetzt können Sie Kommentare hinzufügen, bearbeiten oder löschen und sollten sehen, wie wir Ihre lokale Entwicklungsmaschine mit den Ereignissen aufrufen, wobei Ihr Test-API Key verwendet wird. Es kann eine Verzögerung von bis zu 30 Sekunden geben, bis die Ereignisse Ihre Maschine erreichen.
Einrichtung
Führen Sie für localhost dieselben Schritte aus wie für die Produktionsumgebung. Stellen Sie sicher, dass Sie Produktionsdomains und API Secrets eingerichtet haben.
Zuerst navigieren Sie zum Webhooks admin. Dies ist über Manage Data -> Webhooks zugänglich.
Die Konfigurationsseite sieht wie folgt aus:
Auf dieser Seite können Sie Endpunkte für jede Art von Kommentarereignis angeben.
Für jede Ereignisart klicken Sie unbedingt auf Send Test Payload, um sicherzustellen, dass Sie Ihre Integration korrekt eingerichtet haben. Siehe den nächsten Abschnitt, "Testing", für Details.
Testen
Im Webhooks-Admin gibt es Send Test Payload-Schaltflächen für jeden Ereignistyp (Create, Update, Delete). Die Create- und Update-Ereignisse senden ein Dummy WebhookComment-Objekt, während beim Testen von Delete ein Dummy-Anfragekörper mit nur einer ID gesendet wird.
Überprüfung der Payloads
When testing your webhook integration, verify the incoming requests include the following headers:
token- Ihr API-SecretX-FastComments-Timestamp- Unix-Zeitstempel (Sekunden)X-FastComments-Signature- HMAC-SHA256-Signatur
Verwenden Sie die HMAC-Signaturprüfung, um sicherzustellen, dass die Payloads authentisch sind.
Test-Tools
Sie können Werkzeuge wie webhook.site oder ngrok verwenden, um eingehende Webhook-Payloads während der Entwicklung zu untersuchen.
Ereignistypen
- Create Event: Wird ausgelöst, wenn ein neuer Kommentar erstellt wird. Standardmethode: PUT
- Update Event: Wird ausgelöst, wenn ein Kommentar bearbeitet wird. Standardmethode: PUT
- Delete Event: Wird ausgelöst, wenn ein Kommentar gelöscht wird. Standardmethode: DELETE
Jedes Ereignis enthält die vollständigen Kommentardaten im Anfragekörper (siehe Datenstrukturen für das Payload-Format).
Datenstrukturen
Die einzige Struktur, die über Webhooks gesendet wird, ist das WebhookComment-Objekt, unten in TypeScript dargestellt.
Die Struktur des WebhookComment-Objekts
Die "Create"-Event-Struktur
Der Request-Body des "create"-Events ist ein WebhookComment-Objekt.
Die "Update"-Event-Struktur
Der Request-Body des "update"-Events ist ein WebhookComment-Objekt.
Die "Delete"-Event-Struktur
Der Request-Body des "delete"-Events ist ein WebhookComment-Objekt.
Änderung ab 14. Nov 2023
Zuvor enthielt der Request-Body des "delete"-Events nur die Kommentar-ID. Er enthält jetzt den vollständigen Kommentar zum Zeitpunkt der Löschung.
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-Methoden
Sie können die HTTP-Methode für jeden Webhook-Ereignistyp im Admin-Panel konfigurieren:
- Create Event: POST oder PUT (Standard: PUT)
- Update Event: POST oder PUT (Standard: PUT)
- Delete Event: DELETE, POST oder PUT (Standard: DELETE)
Da alle Anfragen eine ID enthalten, sind Create- und Update-Operationen standardmäßig idempotent (PUT). Die wiederholte Zusendung derselben Create- oder Update-Anfrage sollte auf Ihrer Seite keine doppelten Objekte erzeugen.
Request-Header
Jede Webhook-Anfrage enthält folgende Header:
| Header | Description |
|---|---|
Content-Type |
application/json |
token |
Ihr API-Secret |
X-FastComments-Timestamp |
Unix-Zeitstempel (Sekunden), zu dem die Anfrage signiert wurde |
X-FastComments-Signature |
HMAC-SHA256-Signatur (sha256=<hex>) |
Siehe Sicherheit & API-Token für Informationen zur Überprüfung der HMAC-Signatur.
Sicherheit & API-Token
FastComments Webhook-Anfragen enthalten mehrere Authentifizierungsmechanismen zur Sicherheit.
Gesendete Header
| Header | Beschreibung |
|---|---|
token |
Ihr API Secret (zur Abwärtskompatibilität) |
X-FastComments-Timestamp |
Unix-Zeitstempel (Sekunden), zu dem die Anfrage signiert wurde |
X-FastComments-Signature |
HMAC-SHA256-Signatur der Payload |
HMAC-Signaturüberprüfung (empfohlen)
Wir empfehlen dringend, die HMAC-Signatur zu überprüfen, um sicherzustellen, dass Webhook-Payloads authentisch sind und nicht manipuliert wurden.
Signaturformat: sha256=<hex-encoded-signature>
Wie die Signatur berechnet wird:
- Verketten:
timestamp + "." + JSON_payload_body - Berechne HMAC-SHA256 mit Ihrem API Secret als Schlüssel
- Das Ergebnis hexadezimal kodieren
Beispielüberprüfung (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;
}
// Überprüfe, ob der Zeitstempel aktuell ist (innerhalb von 5 Minuten)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
return false; // Schutz vor Replay-Angriffen
}
// Überprüfe Signatur
const payload = JSON.stringify(req.body);
const expectedSignature = crypto
.createHmac('sha256', apiSecret)
.update(`${timestamp}.${payload}`)
.digest('hex');
return signature === `sha256=${expectedSignature}`;
}Beispielüberprüfung (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
# Überprüfe, ob der Zeitstempel aktuell ist
now = int(time.time())
if abs(now - int(timestamp)) > 300:
return False
# Überprüfe Signatur
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}"Beispielüberprüfung (PHP)
function verifyWebhookSignature($headers, $body, $apiSecret) {
$timestamp = $headers['X-FastComments-Timestamp'] ?? null;
$signature = $headers['X-FastComments-Signature'] ?? null;
if (!$timestamp || !$signature) {
return false;
}
// Überprüfe, ob der Zeitstempel aktuell ist (innerhalb von 5 Minuten)
$now = time();
if (abs($now - intval($timestamp)) > 300) {
return false;
}
// Überprüfe Signatur
$payload = json_encode($body, JSON_UNESCAPED_SLASHES);
$message = $timestamp . '.' . $payload;
$expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);
return hash_equals($expectedSignature, $signature);
}Legacy-Authentifizierung
Der token-Header, der Ihr API Secret enthält, wird weiterhin zur Abwärtskompatibilität gesendet. Wir empfehlen jedoch, auf die HMAC-Überprüfung umzusteigen, um die Sicherheit zu verbessern, da diese vor Replay-Angriffen schützt.
Funktionsweise und Umgang mit Wiederholungsversuchen
Alle Änderungen am Comment-Objekt im System lösen ein Ereignis aus, das in eine Warteschlange gelangt.
Das initiale Webhook-Ereignis wird normalerweise innerhalb von sechs Sekunden nach dem Auftreten der Ereignisquelle gesendet.
Sie können diese Warteschlange im Webhooks-Admin überwachen für den Fall, dass Ihre API ausfällt.
Wenn eine Anfrage an Ihre API fehlschlägt, stellen wir sie nach einem Zeitplan erneut in die Warteschlange.
Dieser Zeitplan ist 1 Minute * the retry count. Wenn der Aufruf einmal fehlschlägt, wird er in
einer Minute erneut versucht. Wenn er zweimal fehlschlägt, wird er anschließend zwei Minuten warten, und so weiter. Dies dient dazu, Ihre
API nicht zu überlasten, falls sie aufgrund von Lastproblemen ausfällt.
Webhooks können über die Protokollseite abgebrochen werden.
Zum Abschluss
Dies schließt unsere Webhooks-Dokumentation ab.
Wir hoffen, dass Sie die FastComments-Webhook-Integration leicht verständlich finden und schnell einrichten können.
Wenn Sie der Meinung sind, dass unsere Dokumentation Lücken aufweist, teilen Sie uns dies unten mit.