Webhook je mehanizem, ali integracija, med dvema sistemoma, kjer "producent" (FastComments) sproži dogodek ki ga "potrošnik" (Vi) prejme prek API klica.

FastComments podpira webhooks le za vir Comment.

Podpiramo webhooks za ustvarjanje komentarjev, odstranjevanje in posodobitve.

Vsak od teh se v našem sistemu šteje kot ločen dogodek in kot tak ima različne semantike in strukture za dogodke webhooka.

V skrbniškem vmesniku Webhooks so gumbi Send Test Payload za vsako vrsto dogodka (Create, Update, Delete). Dogodki Create in Update pošljejo testni objekt WebhookComment, medtem ko bo pri testiranju Delete poslan testni telo zahteve, ki vsebuje le ID.

Preverjanje obremenitev

Pri testiranju vaše webhook integracije preverite, ali dohodni zahtevki vsebujejo naslednje glave:

1. token - Vaša API skrivnost
2. X-FastComments-Timestamp - Unix časovni žig (v sekundah)
3. X-FastComments-Signature - HMAC-SHA256 podpis

Uporabite preverjanje HMAC podpisa, da zagotovite pristnost podatkov.

Orodja za testiranje

Med razvojem lahko za pregled vsebine dohodnih webhook zahtevkov uporabite orodja, kot so webhook.site ali ngrok.

Vrste dogodkov

• Create Event: Sproži se, ko je ustvarjen nov komentar. Privzeta metoda: PUT
• Update Event: Sproži se, ko je komentar urejen. Privzeta metoda: PUT
• Delete Event: Sproži se, ko je komentar izbrisan. Privzeta metoda: DELETE

Vsak dogodek vključuje polne podatke komentarja v telesu zahtevka (glejte Strukture podatkov za format podatkov).

Edina struktura, poslana prek webhookov, je objekt WebhookComment, predstavljen v TypeScriptu spodaj.

Struktura objekta WebhookComment

Struktura dogodka "Create"

Request body dogodka "create" je objekt WebhookComment.

Struktura dogodka "Update"

Request body dogodka "update" je objekt WebhookComment.

Struktura dogodka "Delete"

Request body dogodka "delete" je objekt WebhookComment.

Sprememba z dne 14. novembra 2023
Pred tem je request body dogodka "delete" vseboval samo id komentarja. Zdaj vsebuje celoten komentar v času brisanja.

Objekt WebhookComment

Copy Run

1

2interface WebhookComment {

3 /** ID komentarja. **/

4 id: string

5 /** The id or URL that identifies the comment thread. Normalized. **/

6 urlId: string

7 /** URL, ki kaže, kjer je bil komentar objavljen. **/

8 url?: string

9 /** ID uporabnika, ki je pustil komentar. Če je SSO, je predponan z tenant id. **/

10 userId?: string

11 /** E-pošta uporabnika, ki je pustil komentar. **/

12 commenterEmail?: string

13 /** Ime uporabnika, ki se prikaže v komentar-vidžetu. Pri SSO je lahko displayName. **/

14 commenterName: string

15 /** Surovo besedilo komentarja. **/

16 comment: string

17 /** Besedilo komentarja po parsiranju. **/

18 commentHTML: string

19 /** Zunanji ID komentarja. **/

20 externalId?: string

21 /** ID nadrejenega komentarja. **/

22 parentId?: string | null

23 /** UTC datum, ko je bil komentar oddan. **/

24 date: UTC_ISO_DateString

25 /** Kombinirana karma glasov (up - down). **/

26 votes: number

27 votesUp: number

28 votesDown: number

29 /** True, če je bil uporabnik prijavljen, ko je komentiral, ali če je bil komentar overjen, ali če je ob oddaji komentarja preveril svojo sejo. **/

30 verified: boolean

31 /** Datum, ko je bil komentar overjen. **/

32 verifiedDate?: number

33 /** Če je moderator označil komentar kot pregledan. **/

34 reviewed: boolean

35 /** Lokacija ali base64 kodiranje avatarja. Bo base64 le, če je bila ta vrednost poslana z SSO. **/

36 avatarSrc?: string

37 /** Ali je bil komentar ročno ali samodejno označen kot spam? **/

38 isSpam: boolean

39 /** Ali je bil komentar samodejno označen kot spam? **/

40 aiDeterminedSpam: boolean

41 /** Ali so v komentarju slike? **/

42 hasImages: boolean

43 /** Številka strani, na kateri je komentar za vrstni red "Most Relevant". **/

44 pageNumber: number

45 /** Številka strani, na kateri je komentar za vrstni red "Oldest First". **/

46 pageNumberOF: number

47 /** Številka strani, na kateri je komentar za vrstni red "Newest First". **/

48 pageNumberNF: number

49 /** Ali je bil komentar odobren samodejno ali ročno? **/

50 approved: boolean

51 /** Koda lokalizacije (format: en_us) uporabnika, ko je bil komentar napisan. **/

52 locale: string

53 /** @omenitve, zapisane v komentarju, ki so bile uspešno parsirane. **/

54 mentions?: CommentUserMention[]

55 /** Domena, iz katere izvira komentar. **/

56 domain?: string

57 /** Neobvezen seznam ID-jev skupin moderacije, povezanih s tem komentarjem. **/

58 moderationGroupIds?: string[]|null

59}

60

Ko so uporabniki omenjeni v komentarju, se informacije shranijo v seznamu z imenom mentions. Vsak objekt v tem seznamu ima naslednjo strukturo.

Objekt Webhook omemb

Copy Run

1

2interface CommentUserMention {

3 /** ID uporabnika. Pri SSO uporabnikih bo predpona vaš tenant id. **/

4 id: string

5 /** Končno besedilo @mention oznake, vključno s simbolom @. **/

6 tag: string

7 /** Izvirno besedilo @mention oznake, vključno s simbolom @. **/

8 rawTag: string

9 /** Kakšne vrste uporabnik je bil omenjen. user = FastComments.com account. sso = SSOUser. **/

10 type: 'user'|'sso'

11 /** Če se uporabnik odklopi od obvestil, bo to kljub temu nastavljeno na true. **/

12 sent: boolean

13}

14

HTTP Methods

Na administratorskem vmesniku lahko konfigurirate HTTP metodo za vsako vrsto webhook dogodka:

• Create Event: POST ali PUT (privzeto: PUT)
• Update Event: POST ali PUT (privzeto: PUT)
• Delete Event: DELETE, POST ali PUT (privzeto: DELETE)

Ker vse zahteve vsebujejo ID, sta operaciji Create in Update po privzetku idempotentni (PUT). Ponovitev iste zahteve Create ali Update ne bi smela ustvariti podvojenih objektov na vaši strani.

Request Headers

Vsaka webhook zahteva vključuje naslednje glave:

Za informacije o preverjanju HMAC podpisa glejte Varnost in API žetoni.

FastComments webhook zahtevki vsebujejo več mehanizmov za overjanje za zagotavljanje varnosti.

Poslane glave

Preverjanje HMAC podpisa (priporočeno)

Močno priporočamo preverjanje HMAC podpisa, da zagotovite, da so podatki webhooka avtentični in da z njimi ni bilo manipulirano.

Oblika podpisa: sha256=<hex-encoded-signature>

Kako se izračuna podpis:

1. Združi: timestamp + "." + JSON_payload_body
2. Izračunajte HMAC-SHA256 z vašim API skrivnim ključem kot ključem
3. Hex-kodirajte rezultat

Primer preverjanja (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;
    }

    // Preveri, ali je časovni žig svež (v 5 minutah)
    const now = Math.floor(Date.now() / 1000);
    if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
        return false;  // Preprečevanje ponovitvenega napada
    }

    // Preveri podpis
    const payload = JSON.stringify(req.body);
    const expectedSignature = crypto
        .createHmac('sha256', apiSecret)
        .update(`${timestamp}.${payload}`)
        .digest('hex');

    return signature === `sha256=${expectedSignature}`;
}

Primer preverjanja (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

    # Preveri, ali je časovni žig svež
    now = int(time.time())
    if abs(now - int(timestamp)) > 300:
        return False

    # Preveri 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}"

Primer preverjanja (PHP)

function verifyWebhookSignature($headers, $body, $apiSecret) {
    $timestamp = $headers['X-FastComments-Timestamp'] ?? null;
    $signature = $headers['X-FastComments-Signature'] ?? null;

    if (!$timestamp || !$signature) {
        return false;
    }

    // Preveri, ali je časovni žig svež (v 5 minutah)
    $now = time();
    if (abs($now - intval($timestamp)) > 300) {
        return false;
    }

    // Preveri podpis
    $payload = json_encode($body, JSON_UNESCAPED_SLASHES);
    $message = $timestamp . '.' . $payload;
    $expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);

    return hash_equals($expectedSignature, $signature);
}

Zastarelo overjanje

Glava token, ki vsebuje vaš API skrivni ključ, se še vedno pošilja zaradi združljivosti z starejšimi različicami. Vendar priporočamo prehod na preverjanje preko HMAC zaradi boljše varnosti, saj ščiti pred ponovitvenimi napadi.