Webhooks: שליחת אירועי סוכנים למערכות שלכם

Webhooks יוצאים שולחים אירועי סוכנים לכתובות שלכם. כל שליחה חתומה ב-HMAC-SHA256 כדי שתוכלו לוודא שהיא הגיעה מאיתנו.

Webhooks מאפשרים למערכות שלכם להגיב למה שסוכני Fine Structure עושים. כשאירוע מתרחש, אנחנו שולחים HTTP POST עם גוף JSON לכתובות שהגדרתם. מנהלים subscriptions בעמוד Agent Webhooks ב-finestructure.ai/agent-webhooks, וכל subscription מקבל secret חתימה משלו.

אירוע | נשלח כאשר

conversation.created | שיחת סוכן חדשה מתחילה בכל ערוץ.

message.created | הודעת משתמש או עוזר נוספת לשיחה.

message.completed | תשובת עוזר הסתיימה בהצלחה.

ping | לחצתם על כפתור הבדיקה ב-subscription.

כותרות שליחה

• X-FSE2-Signature: sha256=<HMAC-SHA256 hex של גוף הבקשה הגולמי, עם ה-secret של ה-subscription>.
• X-FSE2-Event: סוג האירוע, למשל message.created.
• X-FSE2-Event-Id: מזהה יציב של האירוע, לשימוש ב-deduplication.
• X-FSE2-Delivery: מזהה ייחודי של ניסיון השליחה הזה.
• X-FSE2-Timestamp: הזמן שבו השליחה נשלחה.

תמיד אמתו את החתימה לפני שאתם סומכים על payload. חשבו HMAC-SHA256 על אותם bytes גולמיים בדיוק עם ה-secret של ה-subscription, המירו ל-hex, הוסיפו prefix של sha256= והשוו מול הכותרת בהשוואה קבועת-זמן.

import crypto from "crypto"

function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex")
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(header || "")
  )
}

import hashlib, hmac

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header or "")

התנהגות שליחה

• החזירו כל סטטוס 2xx בתוך כמה שניות כדי לאשר קבלה.
• שליחות שנכשלו ינסו שוב עם backoff אקספוננציאלי, עד 6 ניסיונות, ואז יעברו ללוג dead-letter שאפשר לבדוק.
• שליחות יכולות להגיע לא לפי הסדר; השתמשו ב-X-FSE2-Event-Id וב-timestamp כדי לסדר ולמנוע כפילויות.
• אפשר לסובב את ה-secret של ה-subscription בכל זמן מעמוד Agent Webhooks.

שמרו את הגוף הגולמי גולמי: אימות חתימה חייב לרוץ על ה-bytes המדויקים ששלחנו. אם ה-framework מפרסר JSON לפני האימות, serialization מחדש יכול לשנות bytes והחתימה לא תתאים. קראו קודם את הגוף הגולמי, אמתו, ורק אז פרסרו.