ווב־הוקים
עם FastComments ניתן לקרוא לנקודת קצה של API בכל פעם שתגובה מתווספת, מתעדכנת או נמחקת מהמערכת שלנו.
אנו מממשים זאת באמצעות webhooks אסינכרוניים על גבי HTTP/HTTPS.
מה הם ווב־הוקים 
Webhook הוא מנגנון, או אינטגרציה, בין שתי מערכות שבה ה"מפיק" (FastComments) שולח אירוע שה"צרכן" (אתה) צורך באמצעות קריאת API.
אירועים ומשאבים נתמכים
FastComments תומכת ב-webhooks רק במשאב Comment.
אנו תומכים ב-webhooks עבור יצירת Comment, הסרה ועד עדכון.
כל אחד מהם נחשב לאירוע נפרד במערכת שלנו ולכן יש לו סמנטיקה שונה ומבנים שונים עבור אירועי webhook.
הגדרות פיתוח מקומי
For Local development, use a tool like ngrok.
In order to simplify keeping the system secure, local development follows the same process as setting up and securing other environments.
שלב 1: הוספת "localhost" לדומיינים בחשבונכם.
Add "localhost" as a domain here.
שלב 2: בחירת מפתח API
We're going to be adding webhook configuration for your domain, so we'll need an API key. You can do that here.
Under "Associate with domain" - select your "localhost" domain.
הערה: לחלופין, ניתן להשתמש בסוד API אחד לכל פעילות בדיקה וסביבות staging. פשוט הוסיפו סוד API עבור "All Domains", ותנו לו שם כמו "test".
Ensure you have an API Secret defined for your production domain(s). Events for all other domains will use the wildcard (testing) secret.
שלב 3: הוספת ה‑Webhook שלכם
While running ngrok or similar tool, set the value for "localhost" here.
When clicking Send Test Payload, we will send two test events to check that you validate the API key.
Once it validates, hit Save.
שלב 4: הוספת תגובה
Now you can add, edit, or delete comments and should see us call your local development machine with the events, using your testing API key. There may be up to 30 seconds delay for the events to reach your machine.
הגדרה
עקבו אחרי אותם הצעדים עבור localhost כפי שהייתם עושים בייצור. ודאו שיש לכם תחומי ייצור והגדרות סודות API.
ראשית, נווטו אל Webhooks admin. ניתן לגשת לכך דרך Manage Data -> Webhooks.
דף התצורה מופיע כך:
בדף זה ניתן לציין נקודות קצה לכל סוג של אירוע תגובה.
עבור כל סוג של אירוע, הקפידו ללחוץ על Send Test Payload כדי לוודא שהגדרתם את האינטגרציה כראוי. ראו את הסעיף הבא, "Testing", לפרטים.
בדיקות
בממשק הניהול של Webhooks יש כפתורי Send Test Payload עבור כל סוג אירוע (Create, Update, Delete). אירועי Create ו-Update שולחים אובייקט WebhookComment מדומה, בעוד שבדיקת Delete תשלח גוף בקשה מדומה עם מזהה בלבד.
אימות המטענים
בעת בדיקת אינטגרציית ה-webhook, וודא שהבקשות הנכנסות כוללות את הכותרות הבאות:
token- סוד ה-API שלךX-FastComments-Timestamp- חותמת זמן Unix (בשניות)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" הכיל רק את מזהה ההערה. כעת הוא מכיל את ההערה המלאה בזמן המחיקה.
Run כאשר משתמשים מתוייגים בהערה, המידע מאוחסן ברשימה שנקראת mentions. כל אובייקט ברשימה זו
יש את המבנה הבא.
Run שיטות 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 כוללת את הכותרות הבאות:
| Header | תיאור |
|---|---|
Content-Type | application/json |
token | סוד ה-API שלך |
X-FastComments-Timestamp | חותמת זמן של Unix (שניות) כאשר הבקשה נחתמה |
X-FastComments-Signature | חתימת HMAC-SHA256 (sha256=<hex>) |
ראו אבטחה וטוקנים של API למידע על אימות חתימת HMAC.
אבטחה ואסימוני API
FastComments webhook requests include multiple authentication mechanisms for security.
Headers Sent
| כותרת | תיאור |
|---|---|
token | סוד ה-API שלך (לתאימות לאחור) |
X-FastComments-Timestamp | חותמת זמן Unix (שניות) כאשר הבקשה נחתמה |
X-FastComments-Signature | חתימת HMAC-SHA256 של המטען |
HMAC Signature Verification (Recommended)
אנו ממליצים בחום לאמת את חתימת ה-HMAC כדי להבטיח שמטעני ה-webhook הם אותנטיים ולא שונו.
פורמט החתימה: sha256=<hex-encoded-signature>
איך החתימה מחושבת:
- צירוף:
timestamp + "." + JSON_payload_body - חישוב HMAC-SHA256 באמצעות סוד ה-API שלך כמפתח
- קידוד תוצאה כ-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 לשיפור האבטחה מכיוון שהיא מגנה מפני התקפות השמעה.
כיצד זה עובד וטיפול בניסיונות חוזרים
כל השינויים לאובייקט Comment במערכת מפעילים אירוע שמסתיים בתור.
אירוע ה-webhook הראשוני נשלח בדרך כלל בתוך שישה שניות מהתרחשות מקור האירוע.
ניתן לנטר את התור הזה בממשק הניהול של Webhooks למקרה שה-API שלך יורד.
אם בקשה ל-API שלך נכשלת, נכניס אותה מחדש לתור על פי לוח זמנים.
לוח הזמנים הוא 1 Minute * the retry count. אם הקריאה נכשלה פעם אחת, היא תנסה שוב בעוד דקה. אם היא תיכשל פעמיים, היא תחכה אז שתי דקות, וכן הלאה. זה כדי שלא נעמיס על ה-API שלך אם הוא יורד מסיבות הקשורות לעומס.
ניתן לבטל את ה-Webhooks מתוך דף היומנים.
לסיכום
זה מסיים את תיעוד ה-Webhooks שלנו.
אנו מקווים שתמצאו את אינטגרציית ה-Webhook של FastComments קלה להבנה ומהירה להקמה.
אם אתם מרגישים שזיהיתם חוסרים בתיעוד שלנו, הודיעו לנו למטה.