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

FastComments תומכת ב-webhooks רק במשאב Comment.

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

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

בממשק ניהול ה-Webhooks יש כפתורי Send Test Payload עבור כל סוג אירוע (Create, Update, Delete). אירועי Create ו-Update שולחים אובייקט WebhookComment מדומה, בעוד שבבדיקת Delete ישלח גוף בקשה מדומה המכיל רק ID.

אימות המטענים

בביצוע בדיקות של שילוב ה-webhook שלך, ודא שהבקשות הנכנסות כוללות את הכותרות הבאות:

1. token - סוד ה-API שלך
2. X-FastComments-Timestamp - חותמת זמן Unix (בשניות)
3. X-FastComments-Signature - חתימת HMAC-SHA256

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

כלי בדיקה

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

סוגי אירועים

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

כל אירוע כולל את נתוני התגובה המלאים בגוף הבקשה (ראה מבני נתונים עבור פורמט המטען).

המבנה היחיד שנשלח דרך webhooks הוא האובייקט WebhookComment, המתואר ב-TypeScript למטה.

מבנה ה-WebhookComment

מבנה האירוע "create"

גוף הבקשה של אירוע ה-"create" הוא אובייקט WebhookComment.

מבנה האירוע "update"

גוף הבקשה של אירוע ה-"update" הוא אובייקט WebhookComment.

מבנה האירוע "delete"

גוף הבקשה של אירוע ה-"delete" הוא אובייקט WebhookComment.

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.

אובייקט WebhookComment

Copy Run

1

2interface WebhookComment {

3 /** ה-id של התגובה. **/

4 id: string

5 /** ה-id או ה-URL שמזהה את שרשור התגובות. מנורמל. **/

6 urlId: string

7 /** ה-URL המצביע היכן הושארה התגובה. **/

8 url?: string

9 /** ה-id של המשתמש שהשאיר את התגובה. אם SSO, יהיה עם קידומת מזהה ה-tenant. **/

10 userId?: string

11 /** הדוא"ל של המשתמש שהשאיר את התגובה. **/

12 commenterEmail?: string

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

14 commenterName: string

15 /** טקסט התגובה הגולמי. **/

16 comment: string

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

18 commentHTML: string

19 /** id חיצוני של התגובה. **/

20 externalId?: string

21 /** ה-id של תגובת האב. **/

22 parentId?: string | null

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

24 date: UTC_ISO_DateString

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

26 votes: number

27 votesUp: number

28 votesDown: number

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

30 verified: boolean

31 /** התאריך שבו התגובה אומתה. **/

32 verifiedDate?: number

33 /** אם מודרטור סמן את התגובה כנבדקה. **/

34 reviewed: boolean

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

36 avatarSrc?: string

37 /** האם התגובה סומנה כספאם ידנית או אוטומטית? **/

38 isSpam: boolean

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

40 aiDeterminedSpam: boolean

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

42 hasImages: boolean

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

44 pageNumber: number

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

46 pageNumberOF: number

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

48 pageNumberNF: number

49 /** האם התגובה אושרה אוטומטית או ידנית? **/

50 approved: boolean

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

52 locale: string

53 /** ה-@mentions שנכתבו בתגובה ונותחו בהצלחה. **/

54 mentions?: CommentUserMention[]

55 /** הדומיין שממנו הגיעה התגובה. **/

56 domain?: string

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

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.

אובייקט המאזכרים של Webhook

Copy Run

1

2interface CommentUserMention {

3 /** ה-id של המשתמש. עבור משתמשי SSO, יהיה עם קידומת מזהה ה-tenant שלכם. **/

4 id: string

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

6 tag: string

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

8 rawTag: string

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

10 type: 'user'|'sso'

11 /** אם המשתמש בחר לא לקבל התראות, ערך זה עדיין יוגדר כ-true. **/

12 sent: boolean

13}

14

שיטות HTTP

ניתן להגדיר את שיטת ה-HTTP עבור כל סוג אירוע webhook בלוח הניהול:

• אירוע Create: POST או PUT (ברירת מחדל: PUT)
• אירוע Update: POST או PUT (ברירת מחדל: PUT)
• אירוע Delete: DELETE, POST, או PUT (ברירת מחדל: DELETE)

מאחר שכל הבקשות מכילות מזהה, פעולות Create ו-Update הן אידמפוטנטיות כברירת מחדל (PUT). חזרה על אותה בקשת Create או Update לא אמורה ליצור אובייקטים כפולים בצד שלכם.

כותרות הבקשה

כל בקשת webhook כוללת את הכותרות הבאות:

ראה אבטחה ומפתחות API למידע על אימות חתימת HMAC.

FastComments webhook requests include multiple authentication mechanisms for security.

Headers Sent

HMAC Signature Verification (Recommended)

We strongly recommend verifying the HMAC signature to ensure webhook payloads are authentic and haven't been tampered with.

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

How the signature is computed:

1. Concatenate: timestamp + "." + JSON_payload_body
2. Compute HMAC-SHA256 using your API Secret as the key
3. Hex-encode the result

Example Verification (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}`;
}

Example Verification (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}"

Example Verification (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

The token header containing your API Secret is still sent for backwards compatibility. However, we recommend migrating to HMAC verification for improved security as it protects against replay attacks.