StreamLive Pro

Webhooks למפתחים: אירועים, חתימה ושליחה

Webhooks של StreamLive Pro למפתחים: מוסיפים כתובת https בהגדרות, מקבלים את stream.started ואירועים נוספים, ובודקים את חתימת HMAC-SHA256 ב-Node או ב-Python.

עודכן 5 בנובמבר 2026 · 4 דק׳ קריאה

Webhook מאפשר ל-StreamLive Pro להודיע לשרת שלכם ברגע שמשהו קורה בחשבון: שידור התחיל, שידור הסתיים, תשלום עבר. מוסיפים כתובת https בהגדרות, בחלק "API ו-Webhooks", מסמנים את האירועים הרצויים, ומאותו רגע כל אירוע נשלח לכתובת כבקשת POST חתומה עם גוף JSON קצר. Webhooks הם חלק ממסלול Studio.

זה עמוד העיון: איך מוסיפים Webhook, מה יש בכל בקשה, איך בודקים את החתימה, ומה בדיוק כללי השליחה. לרעיון הכללי ראו מה זה Webhook? כתובת ברשת שמקבלת הודעות. לקריאה ל-API עם מפתח ראו מפתחות API למפתחים: יצירה, שימוש וביטול.

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

• מסלול Studio. במסלולים אחרים ובתקופת הניסיון החלק מציג "זמין במסלול Studio", והשרת מסרב להוסיף Webhook. אם החשבון יוצא מ-Studio, שום דבר לא נשלח. ה-Webhooks נשארים ברשימה וחוזרים לפעול כשהחשבון חוזר ל-Studio. ראו /pricing.
• כתובת https ציבורית. הכתובת חייבת להתחיל ב-https:// ולהצביע על שרת באינטרנט. כתובות מקומיות ופרטיות (localhost,‏ 10.x,‏ 192.168.x וכדומה) נדחות, גם אם שם דומיין מתחיל להצביע על כתובת כזו רק בהמשך.
• שרת שעונה מהר. השרת צריך להחזיר סטטוס 2xx תוך 10 שניות. עבודה ארוכה עושים אחרי התשובה.

שלבים

1. פותחים את החלק. נכנסים להגדרות ובוחרים "API ו-Webhooks" בתפריט הצד. הכרטיס השני הוא Webhooks.
2. מקלידים כתובת. בשדה "כתובת (https בלבד)" מדביקים את הכתובת של השרת, למשל https://example.com/hooks/streamlive.
3. מסמנים אירועים. האירועים stream.started,‏ stream.ended ו-payment.succeeded מסומנים מראש. מורידים סימון ממה שלא צריך ומסמנים את מה שכן.
4. לוחצים "הוסף webhook". ה-Webhook מופיע ברשימה שמתחת לטופס.
5. מעתיקים עכשיו את סוד החתימה. תיבה בשם "סוד החתימה של ה-webhook" מציגה את הסוד פעם אחת, עם כפתור העתק. שומרים אותו בהגדרות השרת. הוא לא יוצג שוב.
6. מפעילים אירוע אמיתי. אין כפתור בדיקה. מתחילים שידור פרטי קצר ומסיימים אותו: אמורים להגיע stream.started ואחריו stream.ended. ברשימה מופיע "נשלח לאחרונה" עם תאריך ההצלחה האחרונה.

כדי להסיר Webhook לוחצים מחק לידו ומאשרים. אפשר להחזיק עד 10 Webhooks בחשבון.

האירועים

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

איך נראית בקשה

כל שליחה היא POST עם הכותרות (headers) האלה:

הגוף הוא JSON עם שלושה שדות:

{"event":"stream.started","timestamp":"2026-11-05T18:00:00.000Z","data":{"stream_id":"...","title":"Weekly class"}}

השדה timestamp הוא זמן יצירת ההודעה, ב-UTC.

בדיקת החתימה

מחשבים HMAC-SHA256 על הבייטים הגולמיים של הגוף, בדיוק כפי שהגיעו, כשהמפתח הוא הסוד (הטקסט של הסוד כפי שהוצג לכם), ומשווים את תוצאת ה-hex לכותרת X-StreamLive-Signature. לא מפענחים ומקודדים מחדש את ה-JSON לפני כן: רווח אחד ששונה שובר את ההתאמה. ההשוואה צריכה להיות בזמן קבוע (constant-time).

‏Node.js ‏(Express):

const express = require('express');
const crypto = require('crypto');
const app = express();
const SECRET = process.env.STREAMLIVE_WEBHOOK_SECRET;

app.post('/hooks/streamlive', express.raw({ type: 'application/json' }), (req, res) => {
  const got = Buffer.from(req.get('X-StreamLive-Signature') || '', 'utf8');
  const want = Buffer.from(crypto.createHmac('sha256', SECRET).update(req.body).digest('hex'), 'utf8');
  if (got.length === want.length && crypto.timingSafeEqual(got, want)) {
    res.sendStatus(200);                          // answer first
    const msg = JSON.parse(req.body.toString('utf8'));
    console.log(msg.event, msg.data);             // then do the work
  } else {
    res.sendStatus(401);
  }
});

app.listen(3000);

‏Python ‏(Flask):

import hmac, hashlib, json, os
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["STREAMLIVE_WEBHOOK_SECRET"].encode()

@app.post("/hooks/streamlive")
def streamlive():
    raw = request.get_data()
    want = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    got = request.headers.get("X-StreamLive-Signature", "")
    if hmac.compare_digest(got, want):
        msg = json.loads(raw)
        print(msg["event"], msg["data"])
        return "", 200
    return "", 401

כללי השליחה

• ניסיון אחד, 10 שניות. כל אירוע נשלח פעם אחת. אם השרת לא עונה תוך 10 שניות, או עונה במשהו שאינו 2xx, השליחה נחשבת כושלת. אין ניסיון חוזר.
• לא עוקבים אחרי הפניות. תשובת 3xx היא שליחה כושלת. נותנים את הכתובת הסופית.
• כיבוי אחרי 20 כישלונות ברצף. כל הצלחה מאפסת את הספירה. אחרי 20 שליחות כושלות ברצף ה-Webhook מושבת, וברשימה כתוב "מושבת (יותר מדי כישלונות)". אין מתג להדלקה מחדש: מוחקים ומוסיפים שוב (ומקבלים סוד חדש).
• סדר וכפילויות. אירועים נשלחים כשהם קורים, בלי תור. משתמשים ב-stream_id יחד עם שם האירוע כדי לדלג על הודעה שכבר טופלה, ואם אסור לפספס כלום, בודקים מדי פעם גם את המצב דרך ה-API (תיעוד ה-REST API של StreamLive Pro: נקודות קצה ושדות).
• הודעות ישנות. השדה timestamp נמצא בתוך הגוף החתום, כך שאפשר לדחות בבטחה הודעות שנוצרו לפני יותר מכמה דקות.

מה יכול להשתבש

שאלות נפוצות

באיזה מסלול יש Webhooks?

במסלול Studio. במסלולים אחרים ובתקופת הניסיון החלק מסביר ש-Webhooks כלולים ב-Studio, והשרת מסרב להוסיף אחד.

איך יודעים שהבקשה באמת הגיעה מ-StreamLive Pro?

מחשבים HMAC-SHA256 של הגוף הגולמי עם סוד החתימה ומשווים לכותרת X-StreamLive-Signature. אם יש הבדל, דוחים את הבקשה.

האם StreamLive Pro מנסה שוב כששליחה נכשלת?

לא. כל אירוע נשלח פעם אחת, עם זמן המתנה של 10 שניות. אחרי 20 כישלונות ברצף ה-Webhook נכבה.

איבדתי את סוד החתימה. אפשר לראות אותו שוב?

לא. הוא מוצג פעם אחת. מוחקים את ה-Webhook ומוסיפים אותו שוב כדי לקבל סוד חדש.

אפשר לקבל Webhook כשהשידור עולה ב-YouTube?

מקבלים stream.started כשהשידור עולה ב-StreamLive Pro, לא משנה לאילו ערוצים הוא יוצא. האירוע שייך לשידור, לא לרשת מסוימת.

המשך קריאה