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

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

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

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

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

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

בעת בדיקת אינטגרציית ה-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.

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

אובייקט WebhookComment

Copy Run

1

2interface WebhookComment {

3 /** המזהה של ההערה. **/

4 id: string

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

6 urlId: string

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

8 url?: string

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

10 userId?: string

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

12 commenterEmail?: string

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

14 commenterName: string

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

16 comment: string

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

18 commentHTML: string

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

20 externalId?: string

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 /** 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 /** מספר העמוד שבו נמצאת ההערה עבור כיוון המיון "הכי רלוונטי". **/

44 pageNumber: number

45 /** מספר העמוד שבו נמצאת ההערה עבור כיוון המיון "הישנים ביותר תחילה". **/

46 pageNumberOF: number

47 /** מספר העמוד שבו נמצאת ההערה עבור כיוון המיון "החדשים ביותר תחילה". **/

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

כאשר משתמשים מתוייגים בהערה, המידע מאוחסן ברשימה שנקראת mentions. כל אובייקט ברשימה זו יש את המבנה הבא.

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

Copy Run

1

2interface CommentUserMention {

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

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

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

• Create Event: POST או PUT (ברירת מחדל: PUT)
• Update Event: POST או PUT (ברירת מחדל: PUT)
• Delete Event: 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.