עיון בתמיכה ובעזרה

תיעוד למפתחים

Webhooks

בסיום כל שיחה אנחנו שולחים POST של JSON ל־URL שאתם בוחרים — חתום ב־HMAC-SHA256 כדי שתוכלו לוודא שהמטען הגיע מאיתנו. ניסיונות חוזרים על 5xx, יומן שליחות מלא בדשבורד.

פתיחה באפליקציההורדת example.json

מתי ה־Webhook נשלח

Webhook אחד לכל שיחה שמסתיימת. ה־POST נשלח אחרי סיום השיחה (או הצ'אט) וסיום התמליל — תוך שניות בודדות.

כתובת ה־URL מוגדרת לכל סוכן בדשבורד → מפתחים → Webhooks. לכל סוכן URL אחד ומתג הפעלה/כיבוי שלא מאבד את הכתובת.

כותרות בקשה חתומות

בכל POST מופיעות ארבע כותרות מותאמות:

  • X-Webhook-Event — סוג האירוע (לדוגמה conversation.completed).
  • X-Webhook-Id — מזהה שליחות ייחודי; אפשר להשתמש בו ל־idempotency.
  • X-Webhook-Timestamp — שניות Unix בזמן החתימה. לדחות כל מה שעבר 5 דקות.
  • X-Webhook-Signature — sha256=<hex digest> של גוף הבקשה הגולמי, מפותח HMAC עם המפתח הסודי של ה־Webhook לאותו סוכן.

אסור לסמוך על הגוף לפני שהחתימה עוברת.

אימות HMAC (Node.js)

חשוב לוודא את החתימה ב־receiver לפני כל דבר אחר. לדחות אי־התאמה ולדחות כל מה שעבר 5 דקות:

JavaScript
// Node.js — אימות HMAC ודחיית מטענים ישנים מ־5 דקות
import crypto from "node:crypto";

export function verifyWebhook(req, rawBody, secret) {
  const sig = req.headers["x-webhook-signature"] ?? "";
  const ts  = req.headers["x-webhook-timestamp"] ?? "0";
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

חשוב להשתמש ב־req.rawBody (ולא ב־JSON המפוענח) ל־HMAC — פענוח JSON משנה את סדר המפתחות ושובר את ה־digest.

הפניית שדות המטען

המטען המלא מתועד בתוך הדשבורד (עם דוגמאות פר־משתמש). מבנה ברמה גבוהה:

  • event — מחרוזת מבדלת
  • conversation — id, חותמות זמן התחלה/סיום, משך, הפניה לסוכן
  • transcript — מערך תורות עם דובר + טקסט + חותמת זמן
  • summary — שדות סיכום מובנים שה־AI הפיק
  • cost — דקות, מטבע, סיכומים

אחרי כניסה — אפשר לפתוח את הפניית השדות בתוך האפליקציה לכל dot-path. בחירת שדות תאפשר לשלוח רק תת־קבוצה (לדוגמה להוריד תמלילים מסיבות פרטיות).

מטען לדוגמה (להורדה)

מטען קנוני לדוגמה — כל שדה מאוכלס בערכים מציאותיים — זמין ב־/api/developers/webhook-example. אפשר לחיצה ימנית → שמירה בשם, או דרך ה־CTA המשני בראש העמוד.

אחרי כניסה לחשבון, פנייה ל־/api/developers/webhook-example?applyMask=1 תוריד עותק מסונן לפי מסיכת השדות של החשבון — בדיוק המבנה שה־receiver יקבל.

ניסיון חוזר ו־idempotency

אם ה־endpoint מחזיר 2xx — השליחות נרשמת כמוצלחת. כל 4xx נחשב כשל קבוע (ה־endpoint ביקש לא לנסות שוב) והשליחות מסומנת לבדיקה.

5xx ופסקי זמן מפעילים ניסיונות חוזרים אוטומטיים עם backoff מעריכי למשך עד 24 שעות. כל ניסיון חוזר נושא את אותו X-Webhook-Id — לשימוש ל־dedup בצד שלכם.

מסכים קשורים באפליקציה

כל מה שמתואר בתיעוד הציבורי זמין בתוך הדשבורד.

Webhooks

URL + מפתח סודי + יומן שליחות לכל סוכן.

הפניית Webhook

תיעוד שדה־שדה מלא של המטען (נדרשת כניסה).

שדות Webhook

בחירה מדויקת אילו שדות יישלחו ל־receiver.

מפתחות API

אישורים פרוגרמטיים ל־REST API הקרוב.

שאלות נוספות?

נשמח לעזור — ניתן לפנות בדוא״ל לכל שאלת אונבורדינג או אינטגרציה.