Webhook HTTP

ערוץ הwebhook הוא הכניסה הכללית לחיבור כל מערכת שיודעת לבצע POST HTTP. זוהי האפשרות לבחור כאשר אין ערוץ ייעודי למקור שלכם.

מתי להשתמש

• חיבור כלי פנים-ארגוני (ERP, אפליקציה עסקית, gateway תשלומים).
• קבלת אירועים מפלטפורמת צד שלישי המציעה webhooks גנריים.
• הפעלת pipeline מ-cron חיצוני או מ-CI.

הגדרה

1. בעורך המודל, הגדירו את צומת ה-Start עם מקלט Webhook נכנס.
2. betool מייצרת URL ציבורי (https://platform.betool.ai/entries/webhook/<token>).
3. (מומלץ) הגדירו סוד HMAC בתצורת המקלט.

כאשר מוגדר סוד, המערכת שלכם חייבת לחתום על הגוף הגולמי של כל בקשה — HMAC-SHA256(secret, body), בהקסדצימלי — ולהעביר את החתימה ב-header X-Webhook-Signature, בצורה sha256=<hex> או <hex> בלבד. שם ה-header והאלגוריתם (sha256, sha384, sha512) ניתנים להגדרה, למשל כדי להתאים למוסכמה X-Hub-Signature-256 של GitHub. כל בקשה ללא חתימה תקפה נדחית אז (401).

פורמט ה-payload

אתם שולחים כל JSON שתרצו. betool אינה מגבילה את המבנה. ה-payload חשוף ל-pipeline תחת webhook.payload (עם תת-המפתחות שלו); ה-headers, השיטה וה-query string זמינים גם הם תחת webhook.headers, webhook.method ו-webhook.query.

הגוף נקרא לפי ה-Content-Type שלו: JSON מפוענח, טופס (application/x-www-form-urlencoded) כמילון, XML ו-text/* כטקסט גולמי, multipart/form-data כשדות + קבצים מצורפים (webhook.payload._files), וכל סוג אחר (PDF, תמונה, ארכיון…) נשמר כקובץ. גוף דחוס ב-gzip נפרס. גודל מרבי: 50 MB (413 מעבר לכך).

דוגמה:

curl -X POST https://platform.betool.ai/entries/webhook/abc123 \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=$SIGNATURE" \
  -d '{
    "type": "order.created",
    "order_id": "ord_42",
    "amount_cents": 9900,
    "customer_email": "client@exemple.com"
  }'

ה-pipeline יכול אז לחבר סוכן הקורא את webhook.payload.customer_email ו-webhook.payload.amount_cents ישירות.

תגובה

שני מצבי תגובה (response_mode): sync (ברירת מחדל) נחסם עד לתוצאת ה-pipeline ומחזיר אותה בתגובה; ack מחזיר מיד 202 Accepted לאחר הכנסת האירוע לתור עמיד (ה-pipeline מתבצע לאחר מכן, עם ניסיונות חוזרים) — לבחירה עבור ספקים שמגיעים ל-timeout מוקדם.

קריאות GET (אופציה)

כברירת מחדל, רק POST מתקבל: GET מקבל 405. עבור שותף שמחייב שאילתה ב-GET ?action=…, סמנו לקבל גם GET (allow_get). ה-query string הופך אז ל-webhook.payload, באותה צורה כמו POST של טופס: ה-pipeline אינו צריך לדעת באיזו שיטה נעשה שימוש. GET אינו נושא body (נדחה ב-400) ואינו תואם לחתימת HMAC (נדחה ב-405 כל עוד מוגדר סוד). מזהה המועבר ב-query מופיע ביומני הגישה: העדיפו POST כאשר השותף מאפשר זאת.

אבטחה

• חתמו על הבקשות שלכם (HMAC) ברגע שה-endpoint מטפל במשהו מעבר לבדיקות.
• ניתן להחליף את הסוד בכל עת בתצורת המקלט (rotation). לאחר שנשמר, הוא אינו מוצג שוב לעולם: השדה מציג «•••••• שמור — הקלידו כדי להחליף», ו-הסרה מוחקת אותו (החתימה אינה נבדקת עוד).
• ה-payloads מאוחסנים בטקסט ברור בהיסטוריית הביצועים — אל תשלחו נתונים שנועדו להיות מוצפנים בזמן העברה בלבד.