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 administratorskom sučelju za Webhooks nalaze se gumbi Send Test Payload za svaku vrstu događaja (Create, Update, Delete). Create i Update događaji šalju lažni WebhookComment objekt, dok testiranje Delete šalje lažno tijelo zahtjeva s samo ID-jem.

Provjera payloada

Prilikom testiranja vaše webhook integracije, provjerite da dolazni zahtjevi sadrže sljedeća zaglavlja:

1. token - Vaš API Secret
2. X-FastComments-Timestamp - Unix timestamp (sekunde)
3. X-FastComments-Signature - HMAC-SHA256 potpis

Koristite provjeru HMAC potpisa kako biste osigurali da su payloadi autentični.

Alati za testiranje

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

Event Types

• Create Event: Pokreće se kada je kreiran novi komentar. Zadana metoda: PUT
• Update Event: Pokreće se kada je komentar uređivan. Zadana metoda: PUT
• Delete Event: Pokreće se kada se komentar izbriše. Zadana metoda: DELETE

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

Jedina struktura poslana 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.
Prethodno je tijelo zahtjeva za događaj "delete" sadržavalo samo id komentara. Sada sadrži cijeli 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 pokazuje 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 (up - down) glasova. **/

26 votes: number

27 votesUp: number

28 votesDown: number

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

30 verified: boolean

31 /** Datum kada je komentar verificiran. **/

32 verifiedDate?: number

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

34 reviewed: boolean

35 /** Lokacija ili base64 kodiranje avatara. Bit će base64 samo ako je ta vrijednost poslana 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 sortiranje "Most Relevant". **/

44 pageNumber: number

45 /** Broj stranice za sortiranje "Oldest First". **/

46 pageNumberOF: number

47 /** Broj stranice za sortiranje "Newest First". **/

48 pageNumberNF: number

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

50 approved: boolean

51 /** Kod lokalizacije (format: en_us) korisnika kad je komentar pisan. **/

52 locale: string

53 /** @mentions napisani u komentaru koji su uspješno parsirani. **/

54 mentions?: CommentUserMention[]

55 /** Domen od kojeg komentar potječe. **/

56 domain?: string

57 /** Opcionalna lista id-eva moderacijskih grupa 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 webhooka

Copy Run

1

2interface CommentUserMention {

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

4 id: string

5 /** The final @mention tag text, including the @ symbol. **/

6 tag: string

7 /** The original @mention tag text, including the @ symbol. **/

8 rawTag: string

9 /** Kakav tip korisnika je bio označen. user = FastComments.com account. sso = SSOUser. **/

10 type: 'user'|'sso'

11 /** Ako se korisnik odjavi od notifikacija, 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 stvoriti duplicirane objekte 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.