Webhook je mehanizam, ili integracija, između dvaju sustava gdje "proizvođač" (FastComments) pokreće događaj koji "potrošač" (Vi) konzumira putem API poziva.

FastComments podržava webhooks samo za resurs Comment.

Podržavamo webhooks za stvaranje komentara, uklanjanje komentara i ažuriranje komentara.

Svaki od njih smatra se zasebnim događajem u našem sustavu i kao takav ima drugačiju semantiku i strukturu za webhook događaje.

U upravljačkom sučelju za Webhookse postoje gumbi Send Test Payload za svaku vrstu događaja (Create, Update, Delete). Događaji Create i Update šalju lažni WebhookComment objekt, dok testiranje Delete šalje lažno tijelo zahtjeva s samo ID-om.

Provjera payloadova

Prilikom testiranja integracije webhooka, provjerite da dolazni zahtjevi uključuju sljedeća zaglavlja:

1. token - Vaš API tajni ključ
2. X-FastComments-Timestamp - Unix vremenska oznaka (sekunde)
3. X-FastComments-Signature - HMAC-SHA256 potpis

Koristite verifikaciju HMAC potpisa kako biste osigurali autentičnost payloadova.

Alati za testiranje

Možete koristiti alate poput webhook.site ili ngrok za pregled dolaznih webhook payloadova tijekom razvoja.

Vrste događaja

• Create Event: Pokreće se kada se stvori novi komentar. Zadana metoda: PUT
• Update Event: Pokreće se kada se komentar uređuje. Zadana metoda: PUT
• Delete Event: Pokreće se kada se komentar obriše. Zadana metoda: DELETE

Svaki događaj uključuje potpune podatke komentara u tijelu zahtjeva (pogledajte Strukture podataka za format payloada).

Jedina struktura koja se šalje putem webhookova je objekt WebhookComment, prikazan u TypeScriptu u nastavku.

Struktura objekta WebhookComment

Struktura događaja "create"

Tijelo zahtjeva za događaj "create" je objekt WebhookComment.

Struktura događaja "update"

Tijelo zahtjeva za događaj "update" je objekt WebhookComment.

Struktura događaja "delete"

Tijelo zahtjeva za događaj "delete" je objekt WebhookComment.

Promjena od 14. studenog 2023.
Ranije je tijelo zahtjeva za događaj "delete" sadržavalo samo id komentara. Sada sadrži puni komentar u trenutku brisanja.

Objekt WebhookComment

Copy Run

1

2interface WebhookComment {

3 /** ID komentara. **/

4 id: string

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

6 urlId: string

7 /** URL koji upućuje na mjesto gdje je komentar ostavljen. **/

8 url?: string

9 /** ID korisnika koji je ostavio komentar. Ako je SSO, prefiksan s tenant id. **/

10 userId?: string

11 /** Email korisnika koji je ostavio komentar. **/

12 commenterEmail?: string

13 /** Ime korisnika koje se prikazuje u widgetu komentara. Kod SSO može biti displayName. **/

14 commenterName: string

15 /** Neobrađeni tekst komentara. **/

16 comment: string

17 /** Tekst komentara nakon parsiranja. **/

18 commentHTML: string

19 /** Vanjski ID komentara. **/

20 externalId?: string

21 /** ID roditeljskog komentara. **/

22 parentId?: string | null

23 /** UTC datum kada je komentar ostavljen. **/

24 date: UTC_ISO_DateString

25 /** Kombinirani karma (za - protiv) glasova. **/

26 votes: number

27 votesUp: number

28 votesDown: number

29 /** True ako je korisnik bio prijavljen kad je komentirao, ili su potvrdili komentar, ili su potvrdili svoju sesiju kada je komentar ostavljen. **/

30 verified: boolean

31 /** Datum kada je komentar potvrđen. **/

32 verifiedDate?: number

33 /** Ako je moderator označio komentar kao pregledan. **/

34 reviewed: boolean

35 /** Lokacija ili base64 enkodiranje avatara. Bit će base64 samo ako je ta vrijednost proslijeđena s SSO. **/

36 avatarSrc?: string

37 /** Je li komentar ručno ili automatski označen kao spam? **/

38 isSpam: boolean

39 /** Je li komentar automatski označen kao spam? **/

40 aiDeterminedSpam: boolean

41 /** Ima li u komentaru slika? **/

42 hasImages: boolean

43 /** Broj stranice na kojoj se komentar nalazi za smjer sortiranja "Most Relevant". **/

44 pageNumber: number

45 /** Broj stranice na kojoj se komentar nalazi za smjer sortiranja "Oldest First". **/

46 pageNumberOF: number

47 /** Broj stranice na kojoj se komentar nalazi za smjer sortiranja "Newest First". **/

48 pageNumberNF: number

49 /** Je li komentar odobren automatski ili ručno? **/

50 approved: boolean

51 /** Kôd lokalizacije (format: en_us) korisnika kada je komentar napisan. **/

52 locale: string

53 /** @mentioni navedeni u komentaru koji su uspješno parsirani. **/

54 mentions?: CommentUserMention[]

55 /** Domen odakle je komentar. **/

56 domain?: string

57 /** Opcionalna lista ID-eva grupa za moderaciju povezanih s ovim komentarom. **/

58 moderationGroupIds?: string[]|null

59}

60

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.

Objekt spominjanja u webhooku

Copy Run

1

2interface CommentUserMention {

3 /** ID korisnika. Za SSO korisnike bit će prefiksan vašim tenant id. **/

4 id: string

5 /** Konačni tekst @mention taga, uključujući simbol @. **/

6 tag: string

7 /** Izvorni tekst @mention taga, uključujući simbol @. **/

8 rawTag: string

9 /** Koja vrsta korisnika je označena. user = FastComments.com račun. sso = SSOUser. **/

10 type: 'user'|'sso'

11 /** Ako se korisnik odjavi od obavijesti, ovo će i dalje biti postavljeno na true. **/

12 sent: boolean

13}

14

HTTP metode

Možete konfigurirati HTTP metodu za svaku vrstu webhook događaja u administratorskom sučelju:

• Create Event: POST ili PUT (zadano: PUT)
• Update Event: POST ili PUT (zadano: PUT)
• Delete Event: DELETE, POST, ili PUT (zadano: DELETE)

Budući da svi zahtjevi sadrže ID, operacije Create i Update su po defaultu idempotentne (PUT). Ponavljanje istog Create ili Update zahtjeva ne bi trebalo stvarati duplikate objekata na vašoj strani.

Zaglavlja zahtjeva

Svaki webhook zahtjev uključuje sljedeća zaglavlja:

Pogledajte Sigurnost i API tokeni za informacije o provjeri HMAC potpisa.

FastComments webhook zahtjevi uključuju više mehanizama provjere autentičnosti radi sigurnosti.

Zaglavlja koja se šalju

Verifikacija HMAC potpisa (preporučeno)

Toplo preporučujemo provjeru HMAC potpisa kako biste osigurali da su webhook podaci autentični i da nisu izmijenjeni.

Format potpisa: sha256=<hex-encoded-signature>

Kako se potpis izračunava:

1. Spojite: timestamp + "." + JSON_payload_body
2. Izračunajte HMAC-SHA256 koristeći svoj API Secret kao ključ
3. Hex-kodirajte rezultat

Primjer verifikacije (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;
    }

    // Provjerite je li vremenska oznaka svježa (u roku od 5 minuta)
    const now = Math.floor(Date.now() / 1000);
    if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
        return false;  // Sprječavanje replay napada
    }

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

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

Primjer verifikacije (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

    # Provjerite je li vremenska oznaka svježa
    now = int(time.time())
    if abs(now - int(timestamp)) > 300:
        return False

    # Provjerite potpis
    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}"

Primjer verifikacije (PHP)

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

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

    // Provjerite je li vremenska oznaka svježa (u roku od 5 minuta)
    $now = time();
    if (abs($now - intval($timestamp)) > 300) {
        return false;
    }

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

    return hash_equals($expectedSignature, $signature);
}

Naslijeđena autentikacija

token zaglavlje koje sadrži vaš API Secret i dalje se šalje radi kompatibilnosti unatrag. Međutim, preporučujemo prelazak na HMAC provjeru radi poboljšane sigurnosti jer štiti od replay napada.