ווב-הוקים

Webhook הוא מנגנון, או אינטגרציה, בין שתי מערכות שבה ה"מפיק" (FastComments) שולח אירוע שה"צרכן" (אתה) צורך באמצעות קריאת API.

FastComments תומך ב-webhooks עבור משאב ה-Comment בלבד.

אנו תומכים ב-webhooks ליצירת תגובה, הסרה, ולעדכון.

כל אחד מאלה נחשב לאירוע נפרד במערכת שלנו ולכן יש לו סמנטיקה ומבנים שונים עבור אירועי ה-webhook.

כל מספר של נקודות קצה יכול להירשם לאותו אירוע, מהלוח המחוונים או דרך ה-API (see Managing Webhooks via the API). כל webhook נמסר באופן עצמאי.

The new and edit webhook pages have a Send Test Payload button that sends a request to the URL currently in the form, whether or not it has been saved. The Create and Update events send a dummy WebhookComment object, while testing Delete will send a dummy request body with just an ID.

אימות Payloads

When testing your webhook integration, verify the incoming requests include the following headers:

1. X-FastComments-Timestamp - חותמת זמן Unix (שניות)
2. X-FastComments-Signature - חתימת HMAC‑SHA256

Webhooks created before the signature scheme was introduced also receive a token header containing your API Secret. New webhooks do not.

Use the HMAC signature verification to ensure payloads are authentic.

כלי בדיקה

You can use tools like webhook.site or ngrok to inspect incoming webhook payloads during development.

סוגי אירועים

• Create Event: מתבצע כאשר נוצר תגובה חדשה.
• Update Event: מתבצע כאשר תגובה נערכת.
• Delete Event: מתבצע כאשר תגובה נמחקת.

Each webhook is tied to one event and one HTTP method (POST, PUT or DELETE). Each event includes the full comment data in the request body (see Data Structures for the payload format).

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.

שינוי החל מ-14 בנובמבר 2023
בעבר, גוף הבקשה של אירוע "delete" כלל רק את מזהה ההערה. כעת הוא כולל את ההערה המלאה בזמן המחיקה.

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 /** מזהה ההערה. **/

4 id: string

5 /** המזהה או ה-URL שמזהים את שרשרת ההערות. מנורמל. **/

6 urlId: string

7 /** ה-URL שמצביע על המקום שבו הושארה ההערה. **/

8 url: string | null

9 /** מזהה המשתמש שהשאיר את ההערה. אם SSO, מקדים במזהה השוכר. **/

10 userId: string | null

11 /** כתובת האימייל של המשתמש שהשאיר את ההערה. **/

12 commenterEmail: string | null

13 /** שם המשתמש שמופיע בווידג'ט ההערה. עם SSO, יכול להיות displayName. **/

14 commenterName: string

15 /** טקסט ההערה הגולמי. **/

16 comment: string

17 /** טקסט ההערה לאחר ניתוח. **/

18 commentHTML: string

19 /** מזהה חיצוני של ההערה. **/

20 externalId: string | null

21 /** מזהה ההערה ההורה. **/

22 parentId: string | null

23 /** תאריך ה-UTC שבו הושארה ההערה. **/

24 date: UTC_ISO_DateString

25 /** קארמה משולבת (up - down) של ההצבעות. **/

26 votes: number

27 votesUp: number

28 votesDown: number

29 /** אמת אם המשתמש היה מחובר כאשר הוא הגיב, או שהאמת את ההערה, או אם הוא אימת את ההפעלה שלו כאשר ההערה נכתבה. **/

30 verified: boolean

31 /** תאריך ה-UTC שבו האמתה ההערה. **/

32 verifiedDate: UTC_ISO_DateString | null

33 /** אם מודרטור סימן שההערה נבדקה. **/

34 reviewed: boolean

35 /** המיקום, או קידוד base64, של האווטר. יהיה base64 רק אם זו הייתה הערך שהועבר עם SSO. **/

36 avatarSrc: string | null

37 /** האם ההערה סומנה כספאם באופן ידני או אוטומטי? **/

38 isSpam: boolean

39 /** האם ההערה סומנה כספאם באופן אוטומטי? **/

40 aiDeterminedSpam: boolean

41 /** האם יש תמונות בהערה? **/

42 hasImages: boolean

43 /** מספר העמוד שבו נמצאת ההערה עבור מיון "Most Relevant". **/

44 pageNumber: number | null

45 /** מספר העמוד שבו נמצאת ההערה עבור מיון "Oldest First". **/

46 pageNumberOF: number | null

47 /** מספר העמוד שבו נמצאת ההערה עבור מיון "Newest First". **/

48 pageNumberNF: number | null

49 /** האם ההערה אושרה באופן אוטומטי או ידני? **/

50 approved: boolean

51 /** קוד השפה (פורמט: en_us) של המשתמש כאשר נכתבה ההערה. **/

52 locale: string | null

53 /** ה-@mentions שנכתבו בהערה והפוענחו בהצלחה. ריק כאשר אין כאלה. **/

54 mentions: CommentUserMention[]

55 /** הדומיין שממנו ההערה. **/

56 domain: string | null

57 /** מזהי קבוצות המודרציה המשויכים להערה זו. ריק כאשר אין כאלה. **/

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.

אובייקט ה-Mentions של Webhook

Copy Run

1

2interface CommentUserMention {

3 /** מזהה המשתמש. עבור משתמשי SSO, יתווסף לפניו מזהה השוכר שלך. **/

4 id: string

5 /** טקסט תגית @mention הסופי, כולל סימן @. **/

6 tag: string

7 /** טקסט תגית @mention המקורי, כולל סימן @. **/

8 rawTag: string

9 /** סוג המשתמש שסומן. user = חשבון FastComments.com. sso = SSOUser. **/

10 type: 'user'|'sso'

11 /** אם המשתמש בחר לא לקבל התראות, ערך זה עדיין יוגדר ל-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 אבטחה & אסימוני API for מידע על אימות חתימת HMAC.

FastComments webhook requests include multiple authentication mechanisms for security.

Headers Sent

HMAC Signature Verification (Recommended)

אנו ממליצים בחום לאמת את חתימת ה-HMAC כדי להבטיח שמטעני ה-webhook הם אותנטיים ולא שונו.

פורמט החתימה: sha256=<hex-encoded-signature>

איך החתימה מחושבת:

1. צירוף: timestamp + "." + JSON_payload_body
2. חישוב HMAC-SHA256 באמצעות סוד ה-API שלך כמפתח
3. קידוד תוצאה כ-hex

דוגמת אימות (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;  // מניעת התקפת השמעה
    }

    // אימות החתימה
    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);
}

Legacy Authentication

כותרת token המכילה את סוד ה-API שלך עדיין נשלחת לתאימות לאחור. עם זאת, אנו ממליצים לעבור לאימות HMAC לשיפור האבטחה מכיוון שהיא מגנה מפני התקפות השמעה.

Webhooks ניתן גם לנהל דרך ה-REST API. כך אינטגרציות כגון Zapier נרשמות לאירועי תגובות מבלי לגעת בלוח הבקרה, והן פועלות לפי תבנית REST Hooks: הרשמה, קבלת אירועים, ביטול הרשמה.

מנויים ב-API חיים לצד ה-webhooks המוגדרים בלוח הבקרה. אירוע תגובה נשלח לכל webhook שתואם לדומיין שלו, כל אחד כהעברה נפרדת, ללא קשר לאופן שבו נוצר ה-webhook.

Authentication

כל בקשה דורשת את מפתח ה-API שלך בכותרת x-api-key (או בפרמטר השאילתה API_KEY) ו את מזהה השוכר שלך בפרמטר השאילתה tenantId. שני הפרטים מוצגים בעמוד API Secret בלוח הבקרה.

Subscribe

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.

List

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

מחזיר את כל ה-webhooks של השוכר, כולל אלו המנוהלים בלוח הבקרה ("source": "dashboard"). ניתן לסנן באמצעות event, domain או source.

Unsubscribe

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

מחיקת מנוי גם מסירה כל אירוע שעדיין בתור עבורו. רק מנויים שנוצרו דרך ה-API ניתנים למחיקה באופן זה; webhook של לוח הבקרה, או מזהה שאינו קיים בחשבון שלך, מחזיר 404 עם קוד not-found. ניתן לערוך webhooks של לוח הבקרה בעמוד Webhooks.

Payloads and signing

ההעברות משתמשות באותו payload כמו webhooks של לוח הבקרה (ראו Data Structures) ונחתמות באותו סכמת HMAC (ראו Security & API Tokens). מנויים ב-API לעולם לא מקבלים את הכותרת הישנה token, לכן יש לאמת את הכותרת X-FastComments-Signature במקום זאת.

Sample payloads

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

Responding with 410 Gone

אם קצה של מנוי ב-API משיב עם HTTP 410 Gone, FastComments מתייחס לכך כאל ביטול מנוי: המנוי נמחק יחד עם האירועים בתור שלו, ולא מתבצעות עוד העברות. Webhooks המוגדרים בלוח הבקרה אינם נמחקים אוטומטית; עבורם 410 הוא כשל רגיל. כל קוד כשל אחר מנסה שוב ובסופו של דבר משבית את ה-webhook, כפי שמתואר ב‑How it Works & Handling Retries.

Dashboard

מנויים ב-API מופיעים ברשימת ה-Webhooks עם המקור API, שם מנהל יכול לערוך, להשבית, להפעיל מחדש או למחוק אותם.