Webhooks

Webhook је механизам, или интеграција, између два система где "произвођач" (FastComments) покреће догађај који "потрошач" (Ви) прима путем API позива.

FastComments подржава вебхук‑ове само за ресурс Коментар.

Подржавамо вебхук‑ове за креирање коментара, брисање и ажурирање.

Сваки од ових се сматра посебним догађајем у нашем систему и због тога има различиту семантику и структуре за вебхук догађаје.

Било који број крајњих тачака може да се претплати на исти догађај, преко контролне табле или преко API‑ја (погледајте Управљање вебхук‑овима преко API‑ја). Сваки вебхук се испоручује независно.

Нове и странице за уређивање веб‑хукова имају дугме Send Test Payload које шаље захтев на URL који је тренутно у формулару, без обзира да ли је сачуван. Догађаји Create и Update шаљу фиктивни WebhookComment објекат, док тестирање Delete шаље фиктивно тело захтева са само ID‑јем.

Верификација Подаци

При тестирању интеграције вашег веб‑хука, проверите да долазни захтеви садрже следећа заглавља:

1. X-FastComments-Timestamp – Unix временска ознака (секунде)
2. X-FastComments-Signature – HMAC‑SHA256 потпис

Веб‑хукеви креирани пре увођења шеме потписа такође добијају заглавље token које садржи ваш API тајни кључ. Нови веб‑хукеви то не раде.

Користите верификацију HMAC потписа да бисте осигурали да су подаци аутентични.

Алати за тестирање

Можете користити алате као што су webhook.site или ngrok за преглед долазних веб‑хук података током развоја.

Типови Догађаја

• Create Event: Окида се када се креира нови коментар.
• Update Event: Окида се када се коментар уреди.
• Delete Event: Окида се када се коментар избрише.

Сваки веб‑хук је повезан са једним догађајем и једном HTTP методом (POST, PUT или DELETE). Сваки догађај укључује пуне податке о коментару у телу захтева (погледајте Data Structures за формат података).

The only structure sent via webhooks is the WebhookComment object, outlined in TypeScript below.

Структура WebhookComment објекта

Структура догађаја „Create“

The "create" event request body is a WebhookComment object.

Структура догађаја „Update“

The "update" event request body is a WebhookComment object.

Структура догађаја „Delete“

The "delete" event request body is a WebhookComment object.

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.

Every key is always present in the body. When the comment has no value for a field the body carries null (or false for booleans and [] for lists), so the shape of a delivery never varies from one comment to the next.

WebHookComment објекат

Copy Run

1

2interface WebhookComment {

3 /** The id of the comment. **/

4 id: string

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

6 urlId: string

7 /** The URL that points to where the comment was left. **/

8 url: string | null

9 /** The user id that left the comment. If SSO, prefixed with tenant id. **/

10 userId: string | null

11 /** The email of the user left the comment. **/

12 commenterEmail: string | null

13 /** The name of the user that shows in the comment widget. With SSO, can be displayName. **/

14 commenterName: string

15 /** Raw comment text. **/

16 comment: string

17 /** Comment text after parsing. **/

18 commentHTML: string

19 /** Comment external id. **/

20 externalId: string | null

21 /** The id of the parent comment. **/

22 parentId: string | null

23 /** The UTC date when the comment was left. **/

24 date: UTC_ISO_DateString

25 /** Combined karma (up - down) of votes. **/

26 votes: number

27 votesUp: number

28 votesDown: number

29 /** True if the user was logged in when they commented, or their verified the comment, or if they verified their session when the comment was left. **/

30 verified: boolean

31 /** The UTC date when the comment was verified. **/

32 verifiedDate: UTC_ISO_DateString | null

33 /** If a moderator marked the comment reviewed. **/

34 reviewed: boolean

35 /** The location, or base64 encoding, of the avatar. Will only be base64 if that was the value passed with SSO. **/

36 avatarSrc: string | null

37 /** Was the comment manually or automatically marked as spam? **/

38 isSpam: boolean

39 /** Was the comment automatically marked as spam? **/

40 aiDeterminedSpam: boolean

41 /** Are there images in the comment? **/

42 hasImages: boolean

43 /** The page number the comment is on for the "Most Relevant" sort direction. **/

44 pageNumber: number | null

45 /** The page number the comment is on for the "Oldest First" sort direction. **/

46 pageNumberOF: number | null

47 /** The page number the comment is on for the "Newest First" sort direction. **/

48 pageNumberNF: number | null

49 /** Was the comment approved automatically or manually? **/

50 approved: boolean

51 /** The locale code (format: en_us) of the user when the comment was written. **/

52 locale: string | null

53 /** The @mentions written in the comment that were successfully parsed. Empty when there are none. **/

54 mentions: CommentUserMention[]

55 /** The domain the comment is from. **/

56 domain: string | null

57 /** The moderation group ids associated with this comment. Empty when there are none. **/

58 moderationGroupIds: string[]

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.

WebHook Mentions објекат

Copy Run

1

2interface CommentUserMention {

3 /** The user id. For SSO users, this will have your tenant id prefixed. **/

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 /** What type of user was tagged. user = FastComments.com account. sso = SSOUser. **/

10 type: 'user'|'sso'

11 /** If the user opts out of notifications, this will still be set to true. **/

12 sent: boolean

13}

14

HTTP методи

You can configure the HTTP method for each webhook event type in the admin panel:

• Create Event: POST or PUT (default: PUT)
• Update Event: POST or PUT (default: PUT)
• Delete Event: DELETE, POST or PUT (default: DELETE)

Since all requests contain an ID, Create and Update operations are idempotent by default (PUT). Repeating the same Create or Update request should not create duplicate objects on your side.

Заглавља захтева

Each webhook request includes the following headers:

See Security & API Tokens for information on verifying the HMAC signature.

FastComments webhook захтеви укључују више механизама аутентификације ради безбедности.

Заглавља која се шаљу

Верификација HMAC потписа (Препоручено)

Снажно препоручујемо верификацију HMAC потписа како бисте били сигурни да су webhook payload-ови аутентични и да нису измењени.

Формат потписа: sha256=<hex-encoded-signature>

Како се потпис израчунава:

1. Конкатенирајте: timestamp + "." + JSON_payload_body
2. Израчунајте HMAC-SHA256 користећи ваш API Secret као кључ
3. Хекс-енкодирајте резултат

Пример верификације (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;
    }

    // Проверите да ли је временска ознака свежа (у року од 5 минута)
    const now = Math.floor(Date.now() / 1000);
    if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
        return false;  // Превенција replay напада
    }

    // Проверите потпис
    const payload = JSON.stringify(req.body);
    const expectedSignature = crypto
        .createHmac('sha256', apiSecret)
        .update(`${timestamp}.${payload}`)
        .digest('hex');

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

Пример верификације (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

    # Проверите да ли је временска ознака свежа
    now = int(time.time())
    if abs(now - int(timestamp)) > 300:
        return False

    # Проверите потпис
    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}"

Пример верификације (PHP)

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

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

    // Проверите да ли је временска ознака свежа (у року од 5 минута)
    $now = time();
    if (abs($now - intval($timestamp)) > 300) {
        return false;
    }

    // Проверите потпис
    $payload = json_encode($body, JSON_UNESCAPED_SLASHES);
    $message = $timestamp . '.' . $payload;
    $expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);

    return hash_equals($expectedSignature, $signature);
}

Наслеђена аутентификација

Заглавље token које садржи ваш API Secret и даље се шаље ради уназадне компатибилности. Међутим, препоручујемо прелазак на HMAC верификацију због побољшане безбедности јер штити од replay напада.

Webhooks такође могу да се управљају преко REST API‑ја. Ово је начин на који интеграције попут Zapier‑а претплаћу се на догађаје коментара без коришћења контролне табле, и прати шаблон REST Hooks: претплата, примање догађаја, одјава.

API претплате постоје паралелно са вебхук‑овима подешеним у контролној табли. Догађај коментара се испоручује сваком вебхуку који одговара његовом домену, сваки као посебна испорука, без обзира како је вебхук креиран.

Аутентификација

Сваки захтев захтева ваш API кључ у заглављу x-api-key (или у параметру упита API_KEY) и ваш tenant ID у параметру упита tenantId. Оба су приказана на страници API Secret у контролној табли.

Претплата

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

Одговор садржи претплату:

{
    "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"
    }
}

Претплата истог URL‑а на исти догађај и домен поново враћа постојећу претплату уместо креирања дупликата, тако да клијент може безбедно поново покушати. Сваки закупац може имати до 50 API претплата.

Листа

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

Враћа све вебхук‑ове за закупца, укључујући оне управљане у контролној табли ("source": "dashboard"). Филтрирајте помоћу event, domain или source.

Одјава

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

Брисање претплате такође одбацује све догађаје који су још у реду за њу. Само претплате креиране преко API‑ја могу се брисати на овај начин; вебхук из контролне табле, или ID који не постоји у вашем налогу, одговара са 404 и кодом not-found. Вебхук‑ови из контролне табле се уређују на страници Webhooks.

Тела захтева и потписивање

Испоруке користе исти payload као вебхук‑ови из контролне табле (види Data Structures) и потписане су истим HMAC шемом (види Security & API Tokens). API претплате никада не примају наследни token заглавље, па проверите X-FastComments-Signature заглавље уместо тога.

Пример тела захтева

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

Враћа најновије коментаре налога у тачно истом облику у коме их испорука носи, тако да интеграција може приказати прави пример података пре него што стигне први догађај. event је опционо и само се верификује, јер сваки догађај испоручује исти објекат коментара. limit подразумевано је 3 и прихвата вредности од 1 до 10. Потрошња је 2 API кредита.

{
    "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
        }
    ]
}

Одговор са статусом 410 Gone

Ако крајња тачка API претплате одговори HTTP статусом 410 Gone, FastComments то сматра одјавом: претплата се брише заједно са својим догађајима у реду, и даље се не покушавају испоруке. Вебхук‑ови подешени у контролној табли се никада аутоматски не бришу; за њих 410 представља уобичајени неуспех. Сваки други статус неуспеха се поново покушава и на крају онемогућава вебхук, као што је описано у How it Works & Handling Retries.

Контролна табла

API претплате се појављују у листи Webhooks са извором API, где администратор може да их уреди, онемогући, поново омогући или избрише.