Webhooki

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 samo za vir Comment.

Podpiramo webhooks za ustvarjanje komentarjev, odstranjevanje in posodobitev.

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

Poljubno število končnih točk se lahko naroči na isti dogodek, iz nadzorne plošče ali prek API-ja (glejte Managing Webhooks via the API). Vsak webhook se dostavi neodvisno.

Strani za nov in urejanje webhook imata gumb Send Test Payload, ki pošlje zahtevo na URL, ki je trenutno v obrazcu, ne glede na to, ali je bil shranjen ali ne. Dogodka Create in Update pošljeta lažni objekt WebhookComment, medtem ko testiranje Delete pošlje lažno telo zahteve samo z ID-jem.

Preverjanje Payloadov

Pri testiranju vaše webhook integracije preverite, ali dohodne zahteve vsebujejo naslednje glave:

1. X-FastComments-Timestamp - Unix časovni žig (sekunde)
2. X-FastComments-Signature - HMAC-SHA256 podpis

Webhooki, ustvarjeni pred uvedbo sheme podpisov, prejmejo tudi glavo token, ki vsebuje vaš API Secret. Novi webhooki je ne prejmejo.

Uporabite preverjanje HMAC podpisa, da zagotovite avtentičnost payloadov.

Orodja za testiranje

Za pregled dohodnih webhook payloadov med razvojem lahko uporabite orodja, kot sta webhook.site ali ngrok.

Vrste dogodkov

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

Vsak webhook je povezan z enim dogodkom in eno HTTP metodo (POST, PUT ali DELETE). Vsak dogodek vključuje celotne podatke komentarja v telesu zahteve (glejte Data Structures za format payloada).

Edina struktura, poslana prek webhookov, je objekt WebhookComment, prikazan v TypeScript spodaj.

Struktura objekta WebhookComment

Struktura dogodka "Create"

Telo zahteve dogodka create je objekt WebhookComment.

Struktura dogodka "Update"

Telo zahteve dogodka update je objekt WebhookComment.

Struktura dogodka "Delete"

Telo zahteve dogodka delete je objekt WebhookComment.

Sprememba od 14. novembra 2023
Prej je telo zahteve dogodka delete vsebovalo le ID komentarja. Zdaj vsebuje celoten komentar v času brisanja.

Vsak ključ je v telesu vedno prisoten. Ko komentar nima vrednosti za polje, telo nosi null
(ali false za logične vrednosti in [] za sezname), tako da se struktura dostave nikoli ne spreminja med komentarji.

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 na mesto, kjer je bil komentar objavljen. **/

8 url: string | null

9 /** ID uporabnika, ki je objavil komentar. Če SSO, je predponjen z ID najemnika. **/

10 userId: string | null

11 /** E‑mail uporabnika, ki je objavil komentar. **/

12 commenterEmail: string | null

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

18 commentHTML: string

19 /** Zunanji ID komentarja. **/

20 externalId: string | null

21 /** ID nadrejenega komentarja. **/

22 parentId: string | null

23 /** Datum v UTC, ko je bil komentar objavljen. **/

24 date: UTC_ISO_DateString

25 /** Kombinirano karma (glasovi gor - dol). **/

26 votes: number

27 votesUp: number

28 votesDown: number

29 /** Resnično, če je bil uporabnik prijavljen, ko je komentiral, ali je potrdil komentar, ali je potrdil sejo, ko je bil komentar objavljen. **/

30 verified: boolean

31 /** Datum v UTC, ko je bil komentar potrjen. **/

32 verifiedDate: UTC_ISO_DateString | null

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

34 reviewed: boolean

35 /** Lokacija ali base64 kodiranje avatarja. Base64 bo le, če je bila ta vrednost posredovana prek SSO. **/

36 avatarSrc: string | null

37 /** Ali je bil komentar ročno ali samodejno označen kot neželen (spam)? **/

38 isSpam: boolean

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

40 aiDeterminedSpam: boolean

41 /** Ali komentar vsebuje slike? **/

42 hasImages: boolean

43 /** Številka strani, na kateri je komentar pri razvrščanju po "Najbolj relevantnih". **/

44 pageNumber: number | null

45 /** Številka strani, na kateri je komentar pri razvrščanju po "Starejši najprej". **/

46 pageNumberOF: number | null

47 /** Številka strani, na kateri je komentar pri razvrščanju po "Novejši najprej". **/

48 pageNumberNF: number | null

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

50 approved: boolean

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

52 locale: string | null

53 /** @omenjave, zapisane v komentarju, ki so bile uspešno razčlenjene. Prazno, ko jih ni. **/

54 mentions: CommentUserMention[]

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

56 domain: string | null

57 /** ID-ji moderacijskih skupin, povezanih s tem komentarjem. Prazno, ko jih ni. **/

58 moderationGroupIds: string[]

59 /** Značke, prikazane poleg imena komentatorja pri tem komentarju, v času nastanka dogodka. Prazno, ko jih ni. **/

60 badges: CommentUserBadgeInfo[]

61}

62

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

Objekt omemb Webhook

Copy Run

1

2interface CommentUserMention {

3 /** ID uporabnika. Za SSO uporabnike bo predponjen z ID najemnika. **/

4 id: string

5 /** Končni besedilni niz @omenjave, vključno s simbolom @. **/

6 tag: string

7 /** Izvirni besedilni niz @omenjave, vključno s simbolom @. **/

8 rawTag: string

9 /** Vrsta označenega uporabnika. 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

Vsak vnos v seznamu badges ima naslednjo strukturo. Za vrste značk si oglejte vodič po značkah.

Objekt značke Webhook

Copy Run

1

2interface CommentUserBadgeInfo {

3 /** ID značke, dodeljene temu uporabniku. **/

4 id: string

5 /** Vrsta značke. **/

6 type: number

7 /** Opis značke, prikazan ob prehodu z miško. **/

8 description: string

9 /** Besedilo, prikazano na znački. **/

10 displayLabel?: string | null

11 /** Slika, prikazana za značko, če jo uporablja. **/

12 displaySrc?: string | null

13 backgroundColor?: string | null

14 borderColor?: string | null

15 textColor?: string | null

16 /** Dodatni CSS razred, uporabljen za značko. **/

17 cssClass?: string | null

18}

19

HTTP metode

Metodo HTTP za vsak tip webhook dogodka lahko nastavite v skrbniškem vmesniku:

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

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

Glave zahteve

Vsaka zahteva webhooka vključuje naslednje glave:

Za informacije o preverjanju HMAC podpisa si oglejte 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.

Spletne kljuke (webhooks) je mogoče upravljati tudi prek REST API. Na ta način se integracije, kot je Zapier, naročijo na dogodke komentarjev brez uporabe nadzorne plošče, in sledi vzorcu REST Hooks: naroči se, prejmi dogodke, odjavi se.

API-naročnine obstajajo poleg spletnih kljuk, konfiguriranih v nadzorni plošči. Dogodek komentarja se dostavi vsaki spletni kljuki, ki se ujema z njeno domeno, vsaka kot svoja dostava, ne glede na to, kako je bila spletna kljuka ustvarjena.

Avtentikacija

Vsaka zahteva potrebuje vaš API ključ v glavi x-api-key (ali parameter poizvedbe API_KEY) in vaš ID najemnika v parametru poizvedbe tenantId. Oba sta prikazana na strani API Secret v nadzorni plošči.

Naročnina

POST https://fastcomments.com/api/v1/webhooks?tenantId=YOUR_TENANT_ID
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "url": "https://hooks.zapier.com/hooks/catch/123/abc",
    "event": "comment-created"
}

Odgovor vsebuje naročnino:

{
    "status": "success",
    "webhook": {
        "id": "66f1c4c1e7a2b3d4f5a6b7c8",
        "url": "https://hooks.zapier.com/hooks/catch/123/abc",
        "event": "comment-created",
        "domain": "*",
        "method": "POST",
        "source": "api",
        "enabled": true,
        "createdAt": "2026-09-08T12:00:00.000Z"
    }
}

Če se isti URL znova naroči na isti dogodek in domeno, se vrne obstoječa naročnina namesto da bi ustvarila podvojeno, tako da lahko odjemalec varno poskusi znova. Vsak najemnik ima lahko do 50 API-naročnin.

Seznam

GET https://fastcomments.com/api/v1/webhooks?tenantId=YOUR_TENANT_ID

Vrne vsako spletno kljuko za najemnika, vključno s tistimi, ki jih upravlja nadzorna plošča ("source": "dashboard"). Filtrirajte z event, domain ali source.

Odjava

DELETE https://fastcomments.com/api/v1/webhooks/SUBSCRIPTION_ID?tenantId=YOUR_TENANT_ID

Brisanje naročnine tudi zavrže vse dogodke, ki so še v čakalni vrsti zanjo. Na ta način je mogoče izbrisati samo naročnine, ustvarjene prek API; spletna kljuka iz nadzorne plošče ali ID, ki ne obstaja na vašem računu, odgovori z 404 in kodo not-found. Spletne kljuke iz nadzorne plošče se urejajo na strani Webhooks.

Tovorni podatki in podpisovanje

Dostave uporabljajo isti tovor kot spletne kljuke iz nadzorne plošče (glejte Data Structures) in so podpisane z isto shemo HMAC (glejte Security & API Tokens). API-naročnine nikoli ne prejmejo zastarele glave token, zato namesto tega preverite glavo X-FastComments-Signature.

Vzorčni tovorni podatki

GET https://fastcomments.com/api/v1/webhooks/sample-payloads?tenantId=YOUR_TENANT_ID&event=comment-created&limit=3

Vrne najnovejše komentarje računa v točno isti obliki, kot jo nosi dostava, tako da lahko integracija prikaže resnične vzorčne podatke, preden prispe prvi dogodek. event je neobvezen in se samo preveri, saj vsak dogodek dostavi isti objekt komentarja. limit je privzeto 3 in sprejme vrednosti od 1 do 10. Stane 2 API kredita.

{
    "status": "success",
    "payloads": [
        {
            "id": "66f1c4c1e7a2b3d4f5a6b7c8",
            "urlId": "https://example.com/blog/hello-world",
            "commenterName": "Jane Reader",
            "comment": "Great article!",
            "date": "2026-09-08T12:00:00.000Z",
            "approved": true
        }
    ]
}

Odgovarjanje s 410 Gone

Če končna točka API-naročnine odgovori s HTTP 410 Gone, FastComments to obravnava kot odjavo: naročnina se izbriše skupaj s čakajočimi dogodki in nadaljnjih dostav ni več. Spletnih kljuk, konfiguriranih v nadzorni plošči, nikoli ne izbriše samodejno; zanje je 410 običajna napaka. Vsak drug status napake se poskusi znova in sčasoma onemogoči spletno kljuko, kot je opisano v How it Works & Handling Retries.

Nadzorna plošča

API-naročnine se prikažejo na seznamu Webhooks z virom API, kjer jih skrbnik lahko uredi, onemogoči, ponovno omogoči ali izbriše.