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 skrbniku Webhooks so gumbi Send Test Payload za vsako vrsto dogodka (Create, Update, Delete). Dogodka Create in Update pošljeta lažen objekt WebhookComment, medtem ko bo pri testiranju Delete poslano lažno telo zahteve z le ID-jem.

Preverjanje payloadov

Ko testirate integracijo webhooka, preverite, da dohodne zahteve vsebujejo naslednje glave:

1. token - Vaš API skrivni ključ
2. X-FastComments-Timestamp - Unix časovni žig (sekunde)
3. X-FastComments-Signature - HMAC-SHA256 podpis

Uporabite preverjanje HMAC podpisa, da zagotovite pristnost payloadov.

Orodja za testiranje

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

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 celotne podatke komentarja v telesu zahteve (glejte Strukture podatkov za format payloada).

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

Struktura objekta WebhookComment

Struktura dogodka "Create"

Telo zahteve za dogodek "create" je objekt WebhookComment.

Struktura dogodka "Update"

Telo zahteve za dogodek "update" je objekt WebhookComment.

Struktura dogodka "Delete"

Telo zahteve za dogodek "delete" je objekt WebhookComment.

Change as of Nov 14th 2023
Previously the "delete" event request body only contained the comment id. It now contains the full comment at the time of deletion.

Objekt WebhookComment

Copy Run

1

2interface WebhookComment {

3 /** Id komentarja. **/

4 id: string

5 /** Id ali URL, ki identificira nit komentarjev. Normalizirano. **/

6 urlId: string

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

8 url?: string

9 /** Id uporabnika, ki je pustil komentar. Če SSO, s predpono id najemnika. **/

10 userId?: string

11 /** Email uporabnika, ki je pustil komentar. **/

12 commenterEmail?: string

13 /** Ime uporabnika, ki se prikaže v pripomočku za komentarje. Pri SSO je lahko displayName. **/

14 commenterName: string

15 /** Surovo besedilo komentarja. **/

16 comment: string

17 /** Besedilo komentarja po razčlenitvi. **/

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 objavljen. **/

24 date: UTC_ISO_DateString

25 /** Združena karma (glasovi gor - dol). **/

26 votes: number

27 votesUp: number

28 votesDown: number

29 /** True, če je bil uporabnik prijavljen, ko je komentiral, ali je bil komentar preverjen, ali če je uporabnik preveril svojo sejo, ko je bil komentar objavljen. **/

30 verified: boolean

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

32 verifiedDate?: number

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

34 reviewed: boolean

35 /** Lokacija ali base64-kodirana predstavitev avatarja. Bo base64 samo, če je bila ta vrednost posredovana s SSO. **/

36 avatarSrc?: string

37 /** Ali je bil komentar ročno ali samodejno označen kot neželena pošta? **/

38 isSpam: boolean

39 /** Ali je bil komentar samodejno označen kot neželena pošta? **/

40 aiDeterminedSpam: boolean

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

42 hasImages: boolean

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

44 pageNumber: number

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

46 pageNumberOF: number

47 /** Številka strani, na kateri je komentar za smer sortiranja "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, napisane v komentarju, ki so bile uspešno razčlenjene. **/

54 mentions?: CommentUserMention[]

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

56 domain?: string

57 /** Neobvezen seznam id-jev skupin moderiranja, povezanih s tem komentarjem. **/

58 moderationGroupIds?: string[]|null

59}

60

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

Objekt omenitev Webhook

Copy Run

1

2interface CommentUserMention {

3 /** Id uporabnika. Za SSO uporabnike bo imel predpono id najemnika. **/

4 id: string

5 /** Končno besedilo @mention oznake, vključno z znakom @. **/

6 tag: string

7 /** Izvirno besedilo @mention oznake, vključno z znakom @. **/

8 rawTag: string

9 /** Kakšna vrsta uporabnika je bila omenjena. user = račun FastComments.com. sso = SSOUser. **/

10 type: 'user'|'sso'

11 /** Če se uporabnik odjavi od obvestil, bo to še vedno nastavljeno na true. **/

12 sent: boolean

13}

14

HTTP metode

V nadzorni plošči lahko nastavite HTTP metodo za vsako vrsto dogodka webhook:

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

Ker vsi zahtevki vsebujejo ID, sta operaciji Create in Update privzeto idempotentni (PUT). Ponavljanje iste zahteve Create ali Update ne bi smelo ustvariti podvojenih objektov na vaši strani.

Glave zahtev

Vsak webhook zahtevek vključuje naslednje glave:

Oglejte si Varnost in API žetoni za informacije o preverjanju HMAC podpisa.

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.