Webhooks
Med FastComments er det muligt at kalde et API-endpoint, når en kommentar tilføjes, opdateres eller fjernes fra vores system.
Vi opnår dette med asynkrone webhooks over HTTP/HTTPS.
Hvad er Webhooks 
En Webhook er en mekanisme, eller en integration, mellem to systemer hvor "produceren" (FastComments) udløser en begivenhed som "forbrugeren" (dig) modtager via et API-opkald.
Understøttede hændelser og ressourcer
FastComments understøtter kun webhooks for ressourcen Comment.
Vi understøtter webhooks ved oprettelse, fjernelse og opdatering af kommentarer.
Hver af disse betragtes som separate hændelser i vores system og har derfor forskellig semantik og struktur for webhook-hændelserne.
Opsætning til lokal udvikling
For lokal udvikling kan du bruge et værktøj som ngrok.
For at gøre det lettere at holde systemet sikkert, følger lokal udvikling den samme proces som opsætning og sikring af andre miljøer.
Trin 1: Tilføj "localhost" til domæner i din konto.
Tilføj "localhost" som et domæne her.
Trin 2: Vælg en API-nøgle
Vi skal tilføje webhook-konfiguration for dit domæne, så vi har brug for en API-nøgle. Du kan gøre det her.
Under “Associate with domain” - vælg dit “localhost”-domæne.
BEMÆRK: Alternativt kan du bruge én API-hemmelighed til al testaktivitet og staging-miljøer. Tilføj blot en API-hemmelighed for “All Domains”, og giv den et navn som “test”.
Sørg for, at du har en API-hemmelighed defineret for dine produktionsdomæner. Begivenheder for alle andre domæner vil bruge wildcard‑ (test‑) hemmeligheden.
Trin 3: Tilføj din webhook
Mens du kører ngrok eller et lignende værktøj, indstil værdien for “localhost” her.
Når du klikker på Send Test Payload, vil vi sende to test‑begivenheder for at kontrollere, at du validerer API‑nøglen.
Når den er valideret, tryk på Save.
Trin 4: Tilføj en kommentar
Nu kan du tilføje, redigere eller slette kommentarer og bør se, at vi kalder din lokale udviklingsmaskine med begivenhederne ved hjælp af din test‑API‑nøgle. Der kan gå op til 30 sekunder, før begivenhederne når din maskine.
Opsætning
Follow the same steps for localhost as you would production. Ensure you have production domains and API Secrets setup.
First, navigate to the Webhooks admin. 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.
Testning
I Webhooks-administrationen er der Send Test Payload-knapper for hver begivenhedstype (Create, Update, Delete). Create- og Update-begivenhederne sender et dummy WebhookComment-objekt, mens test af Delete sender en dummy request-body med kun et ID.
Verificering af payloads
Når du tester din webhook-integration, skal du sikre, at de indkommende forespørgsler indeholder følgende headere:
token- Din API-secretX-FastComments-Timestamp- Unix-tidsstempel (sekunder)X-FastComments-Signature- HMAC-SHA256-signatur
Brug HMAC-signaturverifikation for at sikre, at payloads er autentiske.
Testværktøjer
Du kan bruge værktøjer som webhook.site eller ngrok til at inspicere indkommende webhook-payloads under udvikling.
Begivenhedstyper
- Create Event: Udløses, når en ny kommentar oprettes. Standardmetode: PUT
- Update Event: Udløses, når en kommentar redigeres. Standardmetode: PUT
- Delete Event: Udløses, når en kommentar slettes. Standardmetode: DELETE
Hver begivenhed indeholder de fulde kommentardata i request-bodyen (se Datastrukturer for payloadformatet).
Datastrukturer
Den eneste struktur, der sendes via webhooks, er WebhookComment-objektet, beskrevet i TypeScript nedenfor.
WebhookComment-objektets struktur
Struktur for "Create"-hændelsen
Request-body'en for "create"-hændelsen er et WebhookComment-objekt.
Struktur for "Update"-hændelsen
Request-body'en for "update"-hændelsen er et WebhookComment-objekt.
Struktur for "Delete"-hændelsen
Request-body'en for "delete"-hændelsen er et WebhookComment-objekt.
Ændring pr. 14. nov. 2023
Tidligere indeholdt request-body'en for "delete"-hændelsen kun kommentarens id. Den indeholder nu den fulde kommentar på tidspunktet for sletningen.
Run Når brugere tagges i en kommentar, gemmes informationen i en liste kaldet mentions. Hvert objekt i den liste
har følgende struktur.
Run HTTP-metoder
Du kan konfigurere HTTP-metoden for hver webhook-hændelsestype i adminpanelet:
- Create Event: POST eller PUT (standard: PUT)
- Update Event: POST eller PUT (standard: PUT)
- Delete Event: DELETE, POST eller PUT (standard: DELETE)
Da alle requests indeholder et ID, er Create- og Update-operationer idempotente som standard (PUT). Gentagelse af samme Create- eller Update-request bør ikke skabe duplikerede objekter hos dig.
Request-headere
Hver webhook-request indeholder følgende headere:
| Header | Beskrivelse |
|---|---|
Content-Type | application/json |
token | Din API Secret |
X-FastComments-Timestamp | Unix-timestamp (sekunder) hvor requesten blev signeret |
X-FastComments-Signature | HMAC-SHA256-signatur (sha256=<hex>) |
Se Sikkerhed & API Tokens for information om verifikation af HMAC-signaturen.
Sikkerhed og API-tokens
FastComments webhook-forespørgsler indeholder flere autentificeringsmekanismer for sikkerhed.
Sendte headere
| Header | Beskrivelse |
|---|---|
token | Din API Secret (for bagudkompatibilitet) |
X-FastComments-Timestamp | Unix-tidsstempel (sekunder) da anmodningen blev signeret |
X-FastComments-Signature | HMAC-SHA256-signatur af payloaden |
HMAC-signaturverifikation (Anbefalet)
Vi anbefaler kraftigt at verificere HMAC-signaturen for at sikre, at webhook-payloads er autentiske og ikke er blevet manipuleret med.
Signaturformat: sha256=<hex-encoded-signature>
Hvordan signaturen beregnes:
- Sammenkæd:
timestamp + "." + JSON_payload_body - Beregn HMAC-SHA256 ved at bruge din API Secret som nøgle
- Hex-enkodér resultatet
Eksempel på verifikation (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;
}
// Bekræft at tidsstemplet er nyligt (inden for 5 minutter)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
return false; // Forebyggelse af replay-angreb
}
// Bekræft signatur
const payload = JSON.stringify(req.body);
const expectedSignature = crypto
.createHmac('sha256', apiSecret)
.update(`${timestamp}.${payload}`)
.digest('hex');
return signature === `sha256=${expectedSignature}`;
}Eksempel på verifikation (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
# Bekræft at tidsstemplet er nyligt
now = int(time.time())
if abs(now - int(timestamp)) > 300:
return False
# Bekræft 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}"Eksempel på verifikation (PHP)
function verifyWebhookSignature($headers, $body, $apiSecret) {
$timestamp = $headers['X-FastComments-Timestamp'] ?? null;
$signature = $headers['X-FastComments-Signature'] ?? null;
if (!$timestamp || !$signature) {
return false;
}
// Bekræft at tidsstemplet er nyligt (inden for 5 minutter)
$now = time();
if (abs($now - intval($timestamp)) > 300) {
return false;
}
// Bekræft signatur
$payload = json_encode($body, JSON_UNESCAPED_SLASHES);
$message = $timestamp . '.' . $payload;
$expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);
return hash_equals($expectedSignature, $signature);
}Ældre autentificering
token-headeren, der indeholder din API Secret, sendes stadig for bagudkompatibilitet. Vi anbefaler dog at migrere til HMAC-verifikation for forbedret sikkerhed, da det beskytter mod replay-angreb.
Hvordan det virker og håndtering af genforsøg
Alle ændringer af Comment-objektet i systemet udløser en begivenhed, som ender i en kø.
Den indledende webhook-begivenhed sendes normalt inden for seks sekunder efter, at begivenhedskilden indtræffer.
Du kan overvåge denne kø i Webhooks-administrationen i tilfælde af, at din API går ned.
Hvis en anmodning til din API fejler, vil vi sætte den i kø igen efter en tidsplan.
Den tidsplan er 1 Minute * the retry count. Hvis kaldet fejler én gang, forsøger det igen om
et minut. Hvis det fejler to gange, vil det derefter vente to minutter, og så videre. Dette er for at undgå, at vi
overbelaster din API, hvis den går ned på grund af belastning.
Webhooks kan annulleres fra log-siden.
Afslutningsvis
Dette afslutter vores Webhooks-dokumentation.
Vi håber, du synes, at FastComments Webhook-integrationen er nem at forstå og hurtig at sætte op.
Hvis du mener, at du har fundet mangler i vores dokumentation, så lad os det vide nedenfor.