Webhooks מכללים

כלל יכול לקרוא ל-URL כאשר הוא מופעל. כך המערכת שלכם יודעת על אירוע מיד, לדוגמה טמפרטורה גבוהה או ניתוק של מכשיר.

לפני שאתם מתחילים

• HAM Systems מפעילה webhooks לכל חשבון בנפרד. אם האפליקציה מציגה Webhooks אינם מופעלים בחשבונך, פנו לתמיכה.
• אתם צריכים כתובת https:// שמקבלת בקשות POST מהאינטרנט.

הוספת webhook לכלל

1. פתחו את תפריט. בקבוצה כלים, הקישו על כללי ענן.
2. פתחו כלל או צרו כלל חדש. ראו יצירת כלל.
3. בפעולות, הקישו על הוסף פעולה.
4. ברשימה, בחרו Webhook.
5. בשדה URL, הקלידו את הכתובת של המערכת שלכם.
6. אם אתם רוצים קריאה גם כאשר הכלל מתאפס, הקישו על הוסף פעולת איפוס ובחרו שוב Webhook.
7. הקישו על שמירה.

מחשב

טלפון

מחשב

טלפון

אם הכתובת לא נכונה, האפליקציה מציגה כתובת URL אינה תקינה.

הבקשה

הפלטפורמה שולחת POST עם גוף JSON ‏(Content-Type: application/json):

{
  "event": "triggered",
  "rule": {
    "id": 4321,
    "name": "Fridge 1 temperature",
    "serialno": "e11:123",
    "this_data": [ { "...": "the rule conditions" } ]
  },
  "device_data": {
    "e11:123": {
      "R": { "T": 912, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
      "O": [],
      "S": { "...": "the device settings" }
    }
  },
  "messages": []
}

שדה	תוכן
event	triggered כאשר הכלל מופעל. resolved כאשר פעולת באיפוס פועלת.
rule.id,‏ rule.name	המספר והשם של הכלל
rule.serialno	המכשיר של הכלל
rule.this_data	התנאים של הכלל
device_data	המצב הנוכחי של כל מכשיר של הכלל, לפי מספר סידורי. אותו פורמט כמו העדכונים של WebSocket.
messages	שגיאות, לדוגמה Failed to get state of e11:123 for rule #4321 כאשר המצב של מכשיר לא זמין

הערכים ב-R הם גולמיים. בדוגמה, T: 912 אומר 9.12 °C. ראו את ההגדרות ב-REST API.

הפלטפורמה מסירה את פרטי ה-WiFi של המכשיר (שם הרשת, הסיסמה והפרטים הארגוניים) מ-device_data.

אבטחת ה-webhook

לבקשה אין חתימה (HMAC). כדי לבדוק שהבקשה מגיעה מהכלל שלכם:

1. צרו סוד אקראי ארוך, לדוגמה עם openssl rand -hex 32.
2. שימו את הסוד ב-query string של הכתובת: https://example.com/ham-hook?token=YOUR_SECRET.
3. במערכת שלכם, דחו כל בקשה שאין בה את ה-token הנכון.

Caution

כל האנשים שיכולים לראות את הכלל יכולים לראות גם את הכתובת עם הסוד. אם האנשים עם הגישה משתנים, שנו את הסוד.

כללים ומגבלות

• הכתובת חייבת להתחיל ב-https://.
• הפלטפורמה לא קוראת לכתובות מקומיות ופרטיות: localhost,‏ 127.0.0.0/8,‏ 10.0.0.0/8,‏ 172.16.0.0/12,‏ 192.168.0.0/16,‏ 169.254.0.0/16,‏ 100.64.0.0/10,‏ 0.0.0.0/8 וכתובות ה-IPv6 הקשורות (::1,‏ fe80:,‏ fc00::/7).
• עד 5 קריאות בכל 60 שניות לכל פעולת webhook של כלל.
• עד 30 קריאות webhook בכל 60 שניות לכל חשבון.
• הפלטפורמה מדלגת על הקריאות שמעל המגבלות. היא לא שולחת אותן מאוחר יותר.
• הפלטפורמה לא בודקת את סטטוס ה-HTTP של התגובה שלכם ולא שולחת את הבקשה שוב.
• לפעולה יכול להיות עיכוב (אחרי). לכלל יש עד 12 פעולות בסך הכול.

בדיקה

לבדיקה ראשונה, השתמשו בשירות ציבורי שמציג את הבקשות שהוא מקבל. צרו כלל עם תנאי קל והסתכלו בגוף הבקשה.

ראו גם

• מה כלל עושה: התראה או פקודה
• נתונים חיים (WebSocket)
• אבטחה