8cadd00d34
Created by Github action --------- Co-authored-by: Crowdin Bot <support+bot@crowdin.com> Co-authored-by: github-actions <github-actions@twenty.com>
87 lines
6.5 KiB
Plaintext
87 lines
6.5 KiB
Plaintext
---
|
|
title: וובהוקים
|
|
image: /images/docs/getting-started/webhooks.png
|
|
info: Discover how to use our Webhooks.
|
|
---
|
|
|
|
<Frame>
|
|
<img src="/images/docs/getting-started/webhooks.png" alt="Header" />
|
|
</Frame>
|
|
|
|
## סקירה כללית
|
|
|
|
וובוקים בתור עשרים משלימים את ה-API על ידי אפשרות לשלוח **התראות בזמן אמת** לאפליקציות שלך כאשר אירועים מסוימים מתרחשים במערכת ה-CRM שלך. במקום לבדוק כל הזמן שינויים ב-API, ניתן להגדיר וובוקים כך שעשרים תשלח **Push** של נתונים למערכת שלך כל פעם שמתרחש אירוע מסוים (לדוגמה, כשנוצר רישום חדש או שמתעדכן רישום קיים). זה עוזר לשמור על סנכרון מיידי ויעיל בין מערכות חיצוניות לבין עשרים.
|
|
|
|
בעזרת וובוקים, עשרים תשלח בקשת HTTP POST ל-URL שציינת, הכוללת פרטים על האירוע. לאחר מכן תוכל לטפל בנתונים אלה באפליקציות שלך (לדוגמה, לעדכן מסד נתונים חיצוני, להפעיל זרימות עבודה או לשלוח התראות).
|
|
|
|
## הגדרת וובוק
|
|
|
|
כדי ליצור וובוק בעשרים, השתמש בהגדרות **API & וובוקים** באפליקציה שלך של עשרים:
|
|
|
|
1. **נווט להגדרות:** באפליקציה שלך של עשרים, עבור אל **הגדרות → API & וובוקים**.
|
|
2. **יצירת וובוק:** תחת **וובוקים** לחץ על **+ ליצור וובוק**.
|
|
3. **הזן URL:** ספק את ה-URL בנקודת השירות שעל השרת שלך, שבו אתה רוצה שעשרים ישלחו בקשות לוובוק. זה צריך להיות URL נגיש לציבור המסוגל לטפל בבקשות POST.
|
|
4. **שמור:** לחץ על **שמור** כדי ליצור את הוובוק. הוובוק החדש יהיה פעיל מיידית.
|
|
|
|
ניתן ליצור מספר וובוקים אם אתה זקוק לשליחת אירועים שונים לנקודות שירות שונות. כל וובוק הוא למעשה מנוי לכל האירועים הרלוונטיים (נכון לעכשיו, עשרים שולחת את כל סוגי האירועים ל-URL הניתן; ייתכן שהגדרת סינון סוגי אירועים ספציפיים היא בתצורת UI). במידה ותצטרך אי פעם להסיר וובוק, תוכל למחוק אותו מאותה דף הגדרות (בחר את הוובוק ובחר מחק).
|
|
|
|
## אירועים ומטענים
|
|
|
|
לאחר שהוגדר וובוק, עשרים תשלח בקשת HTTP POST ל-URL שצוין בכל פעם שאירוע טריגר יתרחש בנתוני ה-CRM שלך. אירועים נפוצים שגורמים לוובוקים כוללים:
|
|
|
|
- **רישום נוצר:** לדוגמה, נוסף אדם חדש (`person.created`), נוצרה חברה חדשה (`company.created`), נוצרה הערה (`note.created`) וכדומה.
|
|
- **רישום עודכן:** לדוגמה, נשמר מידע של אדם קיים (`person.updated`), נערכה רשומת חברה (`company.updated`) ועוד.
|
|
- **רישום נמחק:** לדוגמה, נמחק אדם או חברה (`person.deleted`, `company.deleted`).
|
|
- **אירועים אחרים:** אם רלוונטי, אירועים אחרים של אובייקטים או גירויים מותאמים (למשל, אם משימות או אובייקטים אחרים מעודכנים, היה משתמש בסוגי אירועים דומים כמו `task.created`, `note.updated`, וכו'.).
|
|
|
|
בקשת ה-POST של הוובוק כוללת מטען JSON בגוף שלה. המטען יכלול בדרך כלל לפחות שני דברים: סוג האירוע, והנתונים הקשורים לאותו אירוע (לעיתים קרובות הרשומה שנוצרה/עודכנה). לדוגמה, וובוק לאדם שנוצר בצורה חדשה עשוי לשלוח מטען כמו:
|
|
|
|
```
|
|
{
|
|
"event": "person.created",
|
|
"data": {
|
|
"id": "abc12345",
|
|
"firstName": "Alice",
|
|
"lastName": "Doe",
|
|
"email": "alice@example.com",
|
|
"createdAt": "2025-02-10T15:30:45Z",
|
|
"createdBy": "user_123"
|
|
},
|
|
"timestamp": "2025-02-10T15:30:50Z"
|
|
}
|
|
```
|
|
|
|
בדוגמה זו:
|
|
|
|
- `"event"` מציין מה קרה (`person.created`).
|
|
- `"data"` מכיל את פרטי הרשומה החדשה (אותו מידע שהיית מקבל אם היית מבקש את האדם באמצעות ה-API).
|
|
- `"timestamp"` הוא מתי שהאירוע התרחש (ב-UTC).
|
|
|
|
נקודת השירות שלך צריכה להיות מוכנה לקבל נתוני JSON כאלה דרך POST. בדרך כלל, תפרק את ה-JSON, תסתכל על סוג ה-`"event"` כדי להבין מה קרה, ואז תשתמש ב-`"data"` בהתאם (למשל, ליצור איש קשר חדש במערכת שלך או לעדכן איש קשר קיים).
|
|
|
|
**הערה**: חשוב להגיב עם **סטטוס HTTP 2xx** מנקודת השירות של הוובוק שלך כדי להכיר בקליטה מוצלחת. אם השולח של וובוק עשרים לא מקבל תשובת 2xx, הוא עשוי לשקול שהמסירה נכשלה. (בעתיד, ייתכן שיהיה ניסיון לשלוח מחדש וובוקים שנכשלו, ולכן תמיד יש לשאוף להחזיר 200 OK במהירות האפשרית לאחר עיבוד הנתונים.)
|
|
|
|
## אימות וובוק
|
|
|
|
כדי להבטיח את האבטחה של נקודות השירות של הוובוק שלך, עשרים כוללת חתימה בכותרת `X-Twenty-Webhook-Signature`.
|
|
|
|
החתימה הזו היא הפונקציה HMAC SHA256 של המטען של הבקשה, מחושבת באמצעות הסוד של הוובוק שלך.
|
|
|
|
כדי לאמת את החתימה, יהיה עליך:
|
|
|
|
1. לשרשר את החותמת זמן (מהכותרת `X-Twenty-Webhook-Timestamp`), נקודתיים, ומחרוזת ה-JSON של המטען
|
|
2. לחשוב את הפונקציה HMAC SHA256 באמצעות הסוד של הוובוק שלך בתור המפתח.
|
|
3. להשוות את ה-hex digest התוצאה עם הכותרת של החתימה
|
|
|
|
הנה דוגמה ב-Node.js:
|
|
|
|
```javascript
|
|
const crypto = require("crypto");
|
|
const timestamp = "1735066639761";
|
|
const payload = JSON.stringify({...});
|
|
const secret = "your-secret";
|
|
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
|
|
const signature = crypto.createHmac("sha256", secret)
|
|
.update(stringToSign)
|
|
.digest("hex");
|
|
``` |