BillOS/יכולות/Webhooks

Webhooks שעובדים בשבילכם

קבלו התראות בזמן אמת על המסמכים וההוצאות. בנו אוטומציות שמאזינות לאירועים מדויקים, ב-Make, ב-n8n או בשרת שלכם.

התחילו עכשיו ‹ תיעוד ‹

מאזינים לאירועים בזמן אמת

JSON שהאפליקציה שלכם יכולה להשתמש בו בכל פעם שמשהו קורה למסמך, להוצאה או לייצוא. מזהים וסכומים, לעולם לא תוכן המסמך.

document.issuedמסמך הופק וקיבל מספר. מזהה, סוג, מספר, סכום, לקוח.

document.pdf_readyה-PDF החתום מוכן, עם קישורי מקור והעתק.

document.allocation_assignedמספר הקצאה התקבל מרשות המסים.

expense.recordedהוצאה נרשמה בספר עם מספר רשומה.

export.completedקובץ מבנה אחיד הופק ומוכן להורדה.

POST /webhooks/:id/testשליחת אירוע בדיקה לנקודת הקצה שלכם, מהקונסול או מה-API.

POST https://your-app.example/billos · X-BillOS-Signature: t=1725624131,v1=…

{
  "id": "evt_7s2m…",
  "type": "document.issued",
  "createdAt": "2026-09-06T11:02:11.000Z",
  "data": {
    "documentId": "doc_k3t8…",
    "businessId": "biz_9k…",
    "docType": 320,
    "docNumber": 1042,
    "totalIncVat": 35000,
    "partyName": "דנה לוי"
  }
}

נראות מלאה של המשלוחים

בודקים כל משלוח: האירוע, הניסיון, קוד התשובה של השרת שלכם והניסיון הבא. GET /webhooks/:id/deliveries מחזיר את אותו מידע לקוד.

עד 20 נקודות קצה לכל מפתח
נקודת קצה שנכשלת 100 פעמים ברצף מושבתת, ו-PATCH active מחזיר אותה
משלוחים נשמרים 30 יום

כל הודעה, מובטח שתגיע

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

ניסיונות חוזרים

שישה ניסיונות עם backoff מדקה ועד יממה. רק תשובת 2xx נחשבת הצלחה; redirect נחשב כישלון בכוונה.

חתימה בסגנון Stripe

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

נכתב עם המסמך

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

מתחילים עם Webhooks

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

רושמים נקודת קצה

כתובת https ציבורית ורשימת אירועים. הסוד לחתימה חוזר פעם אחת בתשובה.

POST /webhooks

{ "url": "https://your-app.example/billos", "events": ["document.issued", "expense.recorded"] }
→ 201 { "endpoint": { "id": "whk_2f…", "secret": "whsec_…" } }

מאמתים את החתימה

מחשבים HMAC על הזמן והגוף, משווים בזמן קבוע, ודוחים חותמת בת יותר מחמש דקות.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto'
const [t, v1] = req.headers['x-billos-signature'].split(',').map((p) => p.split('=')[1])
const expected = createHmac('sha256', process.env.BILLOS_WEBHOOK_SECRET).update(t + '.' + rawBody).digest('hex')
if (!timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) return res.status(400).end()

עונים 200, ומהר

אשרו קבלה תוך עשר שניות ועבדו על האירוע אחר כך. שמרו את מזהה המשלוח כדי לדלג על כפילות.