הצטרפות

Webhooks — קבלת עדכון אוטומטי בכל הפקת מסמך (API)

Webhooks — קבלת עדכון אוטומטי בכל הפקת מסמך

מערכת ה-Webhooks מאפשרת לחבר מערכת חיצונית שלכם (CRM, אתר, מחסן וכו') כך שתקבל עדכון בזמן אמת בכל פעם שמופק מסמך במערכת — חשבונית מס, קבלה, חשבון עסקה, הצעת מחיר ועוד. במקום שהמערכת השנייה תבצע חיפוש חוזר כל כמה דקות ("polling"), אנחנו דוחפים אליה הודעת HTTP ברגע שהמסמך נוצר. כל הודעה חתומה דיגיטלית (HMAC-SHA256) כדי שתוכלו לוודא שהיא באמת הגיעה מאיתנו.

המדריך הזה מיועד למפתחים ולבעלי-עסקים טכניים שמחברים מערכת נוספת ל-Invoice Maven. אם עדיין לא הכרתם — כדאי לקרוא קודם על ה-API של המערכת.

שלב 1: איך מגיעים למסך ה-Webhooks

נכנסים למערכת, ובתפריט הצד לוחצים על "הגדרות". ברשימה שנפתחת גוללים עד הסוף ובוחרים "Webhooks" — הפריט האחרון, מיד אחרי "API":

בתפריט הגדרות: Webhooks מיד אחרי API

זהו המסך שייפתח. אם עדיין לא הגדרתם כתובת, יופיע כאן כפתור "+ הוסף":

מסך Webhooks עם כפתור הוסף

שלב 2: הוספת כתובת (Endpoint)

לוחצים על "+ הוסף" וממלאים:

  1. כתובת URL — הכתובת (רצוי HTTPS) של המערכת שלכם שתקבל את העדכון. אנחנו נשלח אליה בקשת POST עם גוף בפורמט JSON.
  2. תאור — טקסט חופשי לזיהוי המנוי (לדוגמה "עדכון ה-CRM").
  3. פעיל — סמנו כדי שהמנוי יפעל. אפשר לכבות זמנית בלי למחוק.
  4. סוגי מסמכים — אפשר לבחור "כל סוגי המסמכים", או לסמן רק סוגים מסוימים (חשבונית מס, קבלה, הצעת מחיר וכו').
  5. מפתח חתימה (Secret) — נוצר אוטומטית ומוצג לקריאה בלבד. העתיקו אותו — תשתמשו בו כדי לאמת את חתימת הבקשות אצלכם (ראו שלב 4).

חלון הוספת Webhook: כתובת URL, תאור, פעיל, סוגי מסמכים ומפתח חתימה

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

שלב 3: מבנה ההודעה שתקבלו

בכל הפקת מסמך נשלחת בקשת POST עם הכותרות (Headers) הבאות:

  • X-Webhook-Event: סוג האירוע — כרגע document.created.
  • X-Webhook-Delivery-Id: מזהה ייחודי של המשלוח (שימושי למניעת כפילויות).
  • X-Webhook-Signature: החתימה בפורמט sha256=<hex> (ראו שלב 4).

גוף ההודעה (JSON) נראה כך:

{
  "event": "document.created",
  "occurred_at": "2026-07-06T13:43:04",
  "company_id": 220,
  "company_name": "העסק שלי בע\"מ",
  "document": {
    "id": "b2532ecb-2cc3-451d-ba6f-7a2921191d69",
    "document_id": 22886,
    "doc_no": 9,
    "doc_type": 5,
    "doc_type_name": "הצעת מחיר",
    "document_date": "06/07/2026",
    "total": 590.0,
    "currency_code": "ILS",
    "customer": {
      "id": "…",
      "customer_id": 1516,
      "name": "אורן ברש",
      "identification": "000000000",
      "email": "oren@example.com"
    },
    "pdf_original": "https://app.invoice-maven.co.il/…/document_….pdf"
  }
}

שימו לב: השדה id של המסמך הוא אותו מזהה (GUID) שמוחזר מ-API הפקת המסמכים ושבו משתמשים בקריאות ה-API האחרות — כך קל לקשר בין המערכות.

שלב 4: אימות החתימה (חשוב לאבטחה)

כדי לוודא שהבקשה באמת הגיעה מ-Invoice Maven ולא זויפה, חשבו HMAC-SHA256 על גוף הבקשה הגולמי (בדיוק כפי שהתקבל) עם ה-Secret שלכם, והשוו לערך שבכותרת X-Webhook-Signature (ללא הקידומת sha256=).

דוגמה ב-Node.js:

const crypto = require("crypto");

function verify(rawBody, signatureHeader, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
  return signatureHeader === expected;
}

דוגמה ב-PHP:

$expected = "sha256=" . hash_hmac("sha256", $rawBody, $secret);
$ok = hash_equals($expected, $signatureHeader);

דוגמה ב-Python:

import hmac, hashlib
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, signature_header)

חשוב: חשבו את החתימה על ה-bytes הגולמיים של הבקשה, לפני כל עיבוד/פענוח של ה-JSON. אם קודם תפענחו ותקודדו מחדש — התווים או הסדר עלולים להשתנות והחתימה לא תתאים.

שלב 5: בדיקה, ניסיונות חוזרים ותגובה

  • שליחת בדיקה: ליד כל מנוי יש כפתור "שליחת בדיקה" ששולח הודעת ping לכתובת שלכם — כך תוכלו לוודא שהחיבור עובד עוד לפני הפקת מסמך אמיתי.
  • תגובה תקינה: על השרת שלכם להחזיר קוד סטטוס 2xx (למשל 200). כל תגובה אחרת נחשבת לכישלון.
  • ניסיונות חוזרים: אם המסירה נכשלה, המערכת תנסה שוב מספר פעמים במרווחים הולכים וגדלים (backoff). מומלץ שהטיפול אצלכם יהיה אידמפוטנטי — כלומר קבלה כפולה של אותו X-Webhook-Delivery-Id לא תיצור כפילות במערכת שלכם.
  • הפסקת שליחה: כדי להפסיק לקבל עדכונים לכתובת מסוימת, פתחו אותה בעריכה והסירו את הסימון "פעיל". כתובת שכבר נשלחו ממנה עדכונים נשמרת לתיעוד ולא ניתנת למחיקה — ביטול הסימון הוא הדרך לכבות אותה.

סיום בהצלחה

זהו! המערכת החיצונית שלכם מעודכנת אוטומטית בזמן אמת, בלי צורך בבדיקות חוזרות. אפשר להגדיר כמה כתובות (מנויים) במקביל — למשל אחת ל-CRM ואחת למחסן.

טיפים נוספים:
• השתמשו בכתובת HTTPS בלבד לאבטחה מרבית.
• שמרו את ה-Secret במקום מאובטח אצלכם ואמתו כל בקשה נכנסת.
• לתיעוד ה-API המלא והאינטראקטיבי, לחצו כאן.

x

הצטרפות