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.

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.

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:

1. token - Din API-secret
2. X-FastComments-Timestamp - Unix-tidsstempel (sekunder)
3. 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).

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.

WebhookComment-objektet

Copy Run

1

2interface WebhookComment {

3 /** Kommentarens id. **/

4 id: string

5 /** Id'et eller URL'en, der identificerer kommentartræet. Normaliseret. **/

6 urlId: string

7 /** URL'en, der peger på hvor kommentaren blev efterladt. **/

8 url?: string

9 /** Bruger-id'et for den, der skrev kommentaren. Hvis SSO, er det præfikset med tenant-id. **/

10 userId?: string

11 /** E-mailen på brugeren, der skrev kommentaren. **/

12 commenterEmail?: string

13 /** Navnet på brugeren, som vises i kommentærwidget'en. Ved SSO kan det være displayName. **/

14 commenterName: string

15 /** Rå kommentartekst. **/

16 comment: string

17 /** Kommentartekst efter parsing. **/

18 commentHTML: string

19 /** Eksternt id for kommentaren. **/

20 externalId?: string

21 /** Id'et på forælderkommentaren. **/

22 parentId?: string | null

23 /** UTC-datoen hvor kommentaren blev skrevet. **/

24 date: UTC_ISO_DateString

25 /** Kombineret karma (op - ned) af stemmer. **/

26 votes: number

27 votesUp: number

28 votesDown: number

29 /** Sandt hvis brugeren var logget ind, da de kommenterede, eller hvis deres kommentar var verificeret, eller hvis de verificerede deres session, da kommentaren blev skrevet. **/

30 verified: boolean

31 /** Datoen hvor kommentaren blev verificeret. **/

32 verifiedDate?: number

33 /** Hvis en moderator markerede kommentaren som gennemgået. **/

34 reviewed: boolean

35 /** Placeringen eller base64-encodningen af avataren. Vil kun være base64 hvis det var den værdi, der blev sendt med SSO. **/

36 avatarSrc?: string

37 /** Blev kommentaren markeret som spam manuelt eller automatisk? **/

38 isSpam: boolean

39 /** Blev kommentaren automatisk markeret som spam? **/

40 aiDeterminedSpam: boolean

41 /** Er der billeder i kommentaren? **/

42 hasImages: boolean

43 /** Sidetallet kommentaren er på for sorteringsretningen "Most Relevant". **/

44 pageNumber: number

45 /** Sidetallet kommentaren er på for sorteringsretningen "Oldest First". **/

46 pageNumberOF: number

47 /** Sidetallet kommentaren er på for sorteringsretningen "Newest First". **/

48 pageNumberNF: number

49 /** Blev kommentaren godkendt automatisk eller manuelt? **/

50 approved: boolean

51 /** Sprogkode (format: en_us) for brugeren da kommentaren blev skrevet. **/

52 locale: string

53 /** De @mentions skrevet i kommentaren, der blev korrekt analyseret. **/

54 mentions?: CommentUserMention[]

55 /** Domænet kommentaren kommer fra. **/

56 domain?: string

57 /** Den valgfrie liste af moderation group ids associeret med denne kommentar. **/

58 moderationGroupIds?: string[]|null

59}

60

Når brugere tagges i en kommentar, gemmes informationen i en liste kaldet mentions. Hvert objekt i den liste har følgende struktur.

Webhook Mentions-objektet

Copy Run

1

2interface CommentUserMention {

3 /** Bruger-id'et. For SSO-brugere vil dette være præfikset med dit tenant-id. **/

4 id: string

5 /** Den endelige @mention-tagtekst, inklusive @-symbolet. **/

6 tag: string

7 /** Den originale @mention-tagtekst, inklusive @-symbolet. **/

8 rawTag: string

9 /** Hvilken type bruger der blev tagget. user = FastComments.com-konto. sso = SSOUser. **/

10 type: 'user'|'sso'

11 /** Hvis brugeren fravælger notifikationer, vil dette stadig være sat til true. **/

12 sent: boolean

13}

14

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:

Se Sikkerhed & API Tokens for information om verifikation af HMAC-signaturen.

FastComments webhook-forespørgsler indeholder flere autentificeringsmekanismer for sikkerhed.

Sendte headere

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:

1. Sammenkæd: timestamp + "." + JSON_payload_body
2. Beregn HMAC-SHA256 ved at bruge din API Secret som nøgle
3. 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.