סקירה כללית

ה-Webhooks של דרימפו מאפשרים ליישום שלך לקבל התראות בזמן אמת כאשר מידע משתנה בארגון הניהול שלך. במקום לבצע Polling מול ה-API, אתה מספק כתובת URL, ואנחנו שולחים בקשת HTTP POST לכתובת זו בכל פעם שמתרחש אירוע רלוונטי.

למה אפשר להירשם #

איך זה עובד #

1. אתה רושם כתובת URL ל-Webhook ובוחר אילו סוגי ישויות תרצה לקבל.
2. אתה יוצר Secret Token (שמור אותו — לא נציג אותו שוב).
3. כאשר אירוע מתרחש בארגון שלך, דרימפו שולחת בקשת POST לכתובת שלך עם Payload בפורמט JSON.
4. השרת שלך מאמת את כותרת X-Webhook-Secret ומעבד את האירוע.

דרישות מנקודת הקצה שלך #

• כתובת HTTPS ציבורית וזמינה
• מחזירה HTTP 2xx בתוך זמן סביר
• מסוגלת לטפל במשלוחים כפולים (Idempotent)
• מאמתת את כותרת X-Webhook-Secret בכל בקשה

התחלה מהירה

הפעל את ה-Webhook הראשון שלך תוך 5 דקות.

שלב 1 — הכן נקודת קצה ציבורית #

נקודת הקצה שלך חייבת להיות:

• כתובת HTTPS ציבורית (לדוגמה: https://your-app.com/darimpo-webhooks)
• לקבל POST עם גוף JSON
• להחזיר 200 OK במהירות האפשרית

שלב 2 — רשום את ה-Webhook במערכת דרימפו #

רישום וניהול Webhooks מתבצע כולו מתוך מערכת דרימפו, לא באמצעות קריאות API.

1. היכנס למערכת דרימפו בכתובת manager.darimpo.com עם שם המשתמש והסיסמה שלך.
2. בתפריט העליון, עבור ל-הגדרות ← Webhooks.
3. לחץ על הוסף Webhook והזן:
   • URL — כתובת נקודת הקצה שלך
   • שם — שם תיאורי להצגה
   • סוגי ישויות — בחר אילו אירועים תרצה לקבל (קריאות שירות, חשבוניות וכו')
4. שמור. המערכת תיצור Webhook פעיל ותציג את ה-Secret Token.

שלב 3 — שמור את ה-Secret Token #

לאחר שמירת ה-Webhook, המערכת מציגה את ה-secretToken:

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

שלב 4 — טפל באירועים נכנסים #

דרימפו תשלח בקשות POST בצורה הבאה:

// Headers
Content-Type: application/json
X-Webhook-Secret: wh_sk_9c2b4a7e8f1d...

// Body
{
  "event": "created",
  "entityType": "tax_invoice",
  "entityId": "01HXYZABC...",
  "webhookId": "01HXYZ...",
  "timestamp": 1744800000000,
  "data": {
    "id": "01HXYZABC...",
    "payment": 500.00,
    "year": 2026,
    "apartmentId": "01HXAPT..."
  }
}

השרת שלך צריך:

1. לאמת שה-X-Webhook-Secret תואם לטוקן ששמרת.
2. להחזיר 200 OK מיד.
3. לעבד את האירוע באופן אסינכרוני.

שלב 5 — בדוק את זה #

הפעל את האירוע מממשק המשתמש של דרימפו (לדוגמה, צור חשבונית מס). נקודת הקצה שלך אמורה לקבל את ההתראה תוך שניות.

אימות ואבטחה

כל בקשת Webhook מדרימפו כוללת כותרת עם Secret Token. עליך לאמת אותה לפני עיבוד ה-Payload.

ה-Secret Token #

ה-secretToken שהוצג ביצירת ה-Webhook הוא מפתח משותף בין השרת שלך לדרימפו. הוא משמש לאימות שכל בקשה נכנסת הגיעה באמת מדרימפו ולא מגורם חיצוני.

חשוב:

• ה-Token מוצג רק ביצירת ה-Webhook ולא ניתן להציגו שוב במערכת.
• אחסן את ה-Token במנהל Secrets או במשתני סביבה — לעולם לא בקוד.

אם איבדת את ה-Token, תצטרך ליצור Webhook חדש, או לבצע רוטציה דרך ממשק הניהול.

הכותרת X-Webhook-Secret #

כאשר דרימפו שולחת Webhook, בקשת ה-HTTP כוללת:

X-Webhook-Secret: wh_sk_9c2b4a7e8f1d...

הערך תואם ל-secretToken שנוצר ברישום ה-Webhook.

מה השרת שלך צריך לעשות #

בכל בקשה נכנסת:

1. קרא את הכותרת X-Webhook-Secret.
2. השווה אותה ל-Token ששמרת עבור Webhook זה.
3. אם הערכים לא תואמים או שהכותרת חסרה — החזר 401 Unauthorized ואל תמשיך לעבד.
4. לשם אבטחה מוגברת, השתמש בהשוואה בזמן קבוע (Timing-safe comparison) כדי למנוע התקפות תזמון.

שיטות עבודה מומלצות באבטחה #

• תמיד הגש את נקודת הקצה שלך מעל HTTPS
• שמור Secrets במנהל Secrets או במשתני סביבה, לעולם לא בקוד
• השתמש בהשוואה בזמן קבוע
• דחה בקשות ללא הכותרת עם 401
• אל תרשום ערכי Secret בלוגים
• אל תקבל Webhooks מעל HTTP רגיל (לא מוצפן)

ניהול Webhooks

רישום, עדכון ומחיקה של Webhooks מתבצעים כולם מתוך מערכת דרימפו, לא באמצעות קריאות API.

רישום Webhook חדש #

1. היכנס למערכת דרימפו בכתובת manager.darimpo.com.
2. בתפריט העליון, עבור ל-הגדרות ← Webhooks.
3. לחץ על הוסף Webhook והזן URL, שם וסוגי ישויות.
4. שמור. המערכת תציג את ה-Secret Token — שמור אותו מיד, הוא לא יוצג שוב.

למדריך המלא #

ניהול מפורט של Webhooks — כולל עריכה, השבתה, מחיקה, רוטציית Secret, וניטור משלוחים — מכוסה במדריך הניהול הנפרד.

לפרטים טכניים על מבנה הבקשות שתקבל, עבור ל-מבנה ה-Payload.

סוגי אירועים

משלוח Webhook מורכב משני מזהים: entityType — איזה סוג של אובייקט השתנה, ו-event — מה קרה לו.

סוגי ישויות #

בעת רישום Webhook, העבר את מזהי הישויות כמספרים שלמים במערך entityTypes.

אירועים #

השדה event ב-Payload יהיה אחד מאלה:

אירועים שנשלחים לכל ישות #

לא כל ישות פולטת כל אירוע. הטבלה הבאה מראה מה תקבל בפועל:

מקרה מיוחד: מחיקת הוצאה

כאשר הוצאה נמחקת, דרימפו עשויה לשלוח שני אירועים:

1. deleted — ההוצאה המקורית
2. created — הוצאת זיכוי (Reversal)

זה משקף את אופן מעקב המחיקות בחשבונאות. טפל בשני האירועים בשילוב שלך.

מקרה מיוחד: זיכויי חשבונית מס

כאשר חשבונית מס מבוטלת עם הודעת זיכוי, אתה מקבל אירוע created לחשבונית חדשה שבה:

• creditType מוגדר
• parentId מפנה לחשבונית המקורית

מבנה ה-Payload

כל משלוחי ה-Webhook חולקים את אותו מעטפת. רק data משתנה לפי סוג הישות.

מעטפת #

{
  "event": "created",
  "entityType": "tax_invoice",
  "entityId": "01HXYZABC...",
  "webhookId": "01HXYZ...",
  "timestamp": 1744800000000,
  "data": { ... }
}

שדות בסיס לכל הישויות #

כל הישויות כוללות את שדות הבסיס הללו:

סוגי שדות לפי סיומת

service_call #

{
  "id": "01HXSC...",
  "createdDate": 1744000000000,
  "status": 1,
  "urgency": 2,
  "reportedDate": 1744000000000,
  "resolvedDate": 0,
  "buildingFacilityId": "01HXBF...",
  "buildingFacilityName": "מעלית בלובי",
  "isPublic": true,
  "isEmergency": false,
  "descriptionDone": "החלפת מנוע"
}

status

urgency

schedual_review #

{
  "id": "01HXSR...",
  "createdDate": 1744000000000,
  "isPartialExecution": false
}

משתף את כל שדות הבסיס של קריאת שירות — reportedDate, buildingFacilityId וכו'.

ל-schedual_review אין שדות Enum ייחודיים.

organization_task #

{
  "id": "01HXOT...",
  "createdDate": 1744000000000,
  "status": 1,
  "urgency": 2,
  "type": 3,
  "reportedDate": 1744000000000,
  "isEmergency": false
}

status

urgency

type (סוג משימה)

tax_invoice #

{
  "id": "01HXTI...",
  "createdDate": 1744000000000,
  "apartmentId": "01HXAPT...",
  "apartmentAddress": "הרצל 123, דירה 4ב",
  "buildingTaxPricingModelName": "רגיל 2026",
  "months": [
    { "month": 1, "year": 2026, "amount": 500.00 },
    { "month": 2, "year": 2026, "amount": 500.00 }
  ],
  "type": 2,
  "transactionType": 0,
  "creditTaxInvoiceId": null
}

type (אמצעי תשלום)

transactionType

expense #

{
  "id": "01HXEX...",
  "createdDate": 1744000000000,
  "taskId": "01HXTASK...",
  "taskType": 1,
  "payment": 1250.50,
  "title": "תחזוקת מעלית",
  "description": "שירות רבעוני",
  "actualPayDate": 1744000000000,
  "repaymentDate": 1744600000000,
  "buildingId": "01HXBLD...",
  "deletedId": 0,
  "parentId": null,
  "paymentType": 2,
  "transactionType": 0,
  "type": 0,
  "isPaid": true,
  "fullAddress": "הרצל 123"
}

paymentType (אמצעי תשלום)

זהה ל-type של חשבונית מס:

type (סוג הוצאה)

transactionType

הערות חשובות #

• שדות לא מסומנים אינם נכללים ב-Payloads — רק השדות המתועדים לעיל.
• שדות חדשים עשויים להתווסף בעתיד. ה-Parser שלך צריך להתעלם משדות לא ידועים.
• תאריך 0 משמעו "לא מוגדר".
• null או parentId חסר משמעם שלישות אין קשר הורה.
• ערכי Enum עשויים להתפתח — התייחס לערכים לא ידועים כ-"לא ידוע" במקום להיכשל.

שיטות עבודה מומלצות

המלצות לבניית אינטגרציית Webhooks אמינה ומאובטחת.

הגב מהר #

החזר 200 OK במהירות האפשרית — רצוי בפחות מ-3 שניות. בצע את העבודה האמיתית ב-Background Job, Queue או Worker.

// טוב: מגיב מיד, מעבד באופן אסינכרוני
app.post('/darimpo-webhooks', (req, res) => {
  res.status(200).send('OK');
  queue.push(req.body);
});

היה Idempotent #

דרימפו עשויה למסור את אותו אירוע יותר מפעם אחת (ניסיונות רשת חוזרים, השרת שלך החזיר 5xx וכו').

השתמש ב-entityId + event + timestamp כמפתח לזיהוי כפילויות:

const key = `${body.entityId}:${body.event}:${body.timestamp}`;
if (await alreadyProcessed(key)) return; // דלג על כפילות
await markProcessed(key);
await doTheWork(body);

מאגרי Idempotency נפוצים: Redis SETNX, אינדקס ייחודי בבסיס נתונים, טבלת Idempotency-key.

טפל בניסיונות חוזרים בחן #

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

אמת את ה-Secret בכל בקשה #

לעולם אל תדלג על אימות חתימה — גם בפיתוח. ראה אימות ואבטחה.

הסדר לא מובטח #

אירועים עשויים להגיע לא לפי סדר. עצב Handlers שישתמשו ב-timestamp או במצב הישות (לא בסדר המשלוח) כמקור האמת.

הירשם בצמצום #

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

התעלם משדות לא ידועים #

דרימפו עשויה להוסיף שדות חדשים ל-Payloads ללא הודעה. Parsers שנכשלים על שדות לא ידועים יישברו.

• JSON.parse(body) — טוב
• אימות סכמה קפדני שדוחה שדות נוספים — רע

רשום הכל בלוגים (בזהירות) #

רשום בלוגים עבור כל משלוח:

• webhookId
• entityId
• event
• timestamp
• סטטוס HTTP שהחזרת

בדיקות #

• פיתוח מקומי: השתמש ב-ngrok או Cloudflare Tunnel כדי לחשוף את השרת המקומי שלך.
• בדיקה: webhook.site נותן לך כתובת חד-פעמית שמציגה את כל הבקשות הנכנסות. מצוין לגילוי.
• Staging: רשום Webhook נפרד שמצביע לסביבת ה-Staging שלך. לעולם אל תבדוק מול פרודקשן.

קצב ונפח #

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

צ'קליסט לפני עלייה לאוויר #

• נקודת קצה HTTPS פרוסה
• Secret מאוחסן במשתני סביבה / מנהל Secrets (לא בקוד)
• השוואת Secret בזמן קבוע
• מפתח Idempotency על כל אירוע
• מחזיר 200 בפחות מ-3 שניות
• מטפל ב-created, updated, ו-deleted (היכן שרלוונטי)
• ניטור / התראות על משלוחים שנכשלו
• נוהל עבודה לרוטציית Secret

צריך עזרה? #

פנה לתמיכת דרימפו עם:

• ה-id של ה-Webhook שלך
• ה-timestamp של המשלוח החסר/כושל
• קוד סטטוס HTTP שהשרת שלך החזיר