דלג לתוכן הראשי
דלגו לתוכן המדריך
מדריך אינטגרציית Webhook של Takbull למפתחים ולמערכות צד שלישי.
Takbull Developers · מדריך למפתחים

מדריך Webhook של תקבול

התראות אירועים בזמן אמת עבור מערכות צד שלישי: תשלום מוצלח, תשלום שנכשל, חשבונית חדשה, הזמנה ממתינה לתשלום והזמנה שננטשה. כולל שלב חתימת אבטחה (Secret) לאימות מקור הבקשה.

סקירה כללית

Takbull שולחת התראות Webhook אל כתובת URL לבחירתכם כאשר אירועים מסוימים מתרחשים במערכת. לדוגמה: תשלום שהושלם בהצלחה, ניסיון תשלום שנכשל, חשבונית חדשה שנוצרה או הזמנה שננטשה על ידי הלקוח.

נקודת הקצה שלכם חייבת להיות נגישה באופן ציבורי, לעבוד באמצעות HTTP/HTTPS, ולהיות מסוגלת לקבל בקשות מהמערכת של Takbull.
POST שליחת גוף בקשה בפורמט JSON או XML אל נקודת הקצה שלכם.
GET שליחת מזהה ההזמנה או החשבונית בפרמטרים של Query String.
Retry במקרה של כשל, Takbull תנסה לשלוח את ההתראה שוב עד 3 ניסיונות בסך הכול.

הגדרת Webhook

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

הגדרות Webhook
הגדרה תיאור
Hook Address כתובת ה־URL המלאה של נקודת הקצה שלכם, לדוגמה: https://yoursite.com/webhooks/takbull
Request Type סוג הבקשה: GET או POST
Request Data Type סוג הנתונים: JSON, XML או Query
Event Trigger Type האירוע שמפעיל את ה־Webhook, למשל תשלום מוצלח, תשלום שנכשל או חשבונית חדשה.

השלב האחרון: חתימת אבטחה (Secret)

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

  1. הפעילו את האפשרות באמצעות המתג בשדה חתימת אבטחה.
  2. העתיקו את ה־Secret באמצעות סמל ההעתקה שלצד המפתח.
  3. שמרו את המפתח בצד השרת בלבד, למשל במשתנה סביבה או במנהל סודות. אין לשלב אותו בקוד דפדפן, באתר ציבורי או בלוגים.
  4. לחצו על ״שמור״ כדי לשמור את הגדרות ה־Webhook.
  5. הגדירו אימות בשרת המקבל באמצעות המפתח ובהתאם למפרט החתימה של תקבול, לפני עיבוד האירוע או ביצוע פעולה עסקית.

חתימת אבטחה (Secret) אופציונלי

אימות שהבקשה נשלחה מתקבול

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

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

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

אירועים נתמכים

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

Event Trigger Types
Event Value Description
General 0 מופעל בכל שינויי מצב הזמנה.
NewInvoice 10 חשבונית חדשה נוצרה.
SuccessPayment 20 תשלום הושלם בהצלחה.
FailedPayment 30 ניסיון תשלום נכשל.
PendingOrder 40 הזמנה חדשה נוצרה וממתינה לתשלום.
AbandonedOrder 50 הזמנה ננטשה על ידי הלקוח.

Headers ופרטי בקשה

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

Headers
Header Value
User-Agent TakbullIPNAgent
Content-Type application/json עבור POST בפורמט JSON בלבד.

POST – JSON Payload עבור אירועי הזמנה

כאשר Request Type = POST ו־ Request Data Type = JSON, גוף הבקשה נשלח כאובייקט JSON.

{
  "Id": 123456,
  "uniqId": "a1b2c3d4-e5f6-...",
  "OrderNumber": 1001,
  "order_reference": "your-internal-ref",
  "CustomerFullName": "Israel Israeli",
  "CustomerEmail": "customer@example.com",
  "CustomerPhone": "0501234567",
  "OrderStatus": 2,
  "StatusCode": 0,
  "StatusDescription": "Success",
  "OrderTotalSum": 250.00,
  "Token": "card-external-token",
  "Last4Digs": "1234",
  "Cardtype": "Visa",
  "Action": "Charge",
  "IsSubscriptionPayment": false
}
הצגת טבלת שדות Order Notification
Order Notification Fields
Field Type Description
Idintegerמזהה הזמנה פנימי.
uniqIdstringמזהה הזמנה ייחודי, UUID.
OrderNumberintegerמספר הזמנה רציף שמוצג לסוחר.
order_referencestringהפניית ההזמנה המותאמת שהועברה בעת checkout.
DealTypeintegerסוג העסקה, 0 = Regular.
CustomerFullNamestringהשם המלא של הלקוח.
CustomerEmailstringכתובת האימייל של הלקוח.
CustomerPhonestringמספר הטלפון של הלקוח.
CustomerIdentitystringמספר תעודת הזהות של הלקוח.
OrderStatusintegerקוד מצב ההזמנה הסופי.
StatusCodeintegerמצב עיבוד פנימי. 0 = success.
StatusDescriptionstringתיאור קריא לאדם של StatusCode.
InvoiceStatusCodeinteger | nullמצב יצירת החשבונית. 0 = success.
InvoiceStatusDescriptionstringתיאור מצב החשבונית.
InvoiceUniqIdstringמזהה ייחודי של החשבונית שנוצרה.
DocumentNumberintegerמספר מסמך רציף.
DocumentTypeintegerסוג המסמך שהופק.
IsSubscriptionPaymentbooleantrue אם זהו חיוב מנוי חוזר.
TransactionIdinteger | nullמזהה עסקה פנימי.
Tokenstringטוקן כרטיס שמור לחיובים עתידיים.
Last4Digsstring4 הספרות האחרונות של הכרטיס.
Cardtypestringמותג הכרטיס, לדוגמה Visa או Mastercard.
OrderTotalSumdecimalהסכום הכולל שחויב.
Actionstringפעולת התשלום שבוצעה, לדוגמה Charge או Refund.
InitialRecuringPaymentStatusCodeintegerמצב הגדרת התשלום החוזר הראשוני.
InitialRecuringPaymentDescriptionstringתיאור מצב הגדרת התשלום החוזר.
SubscriptionStatusCodeintegerקוד מצב עבור חיוב מנוי.
SubscriptionStatusDescriptionstringתיאור עבור מצב חיוב מנוי.

POST – XML Payload

כאשר Request Type = POST ו־ Request Data Type = XML, אותם נתונים נשלחים כאובייקט OrderNotification שעבר סריאליזציה ל־XML.

<?xml version="1.0" encoding="utf-16"?>
<OrderNotification xmlns:xsi="..." xmlns:xsd="...">
  <Id>123456</Id>
  <uniqId>a1b2c3d4-e5f6-...</uniqId>
  <OrderNumber>1001</OrderNumber>
  <CustomerFullName>Israel Israeli</CustomerFullName>
  <OrderStatus>2</OrderStatus>
  <StatusCode>0</StatusCode>
  <StatusDescription>Success</StatusDescription>
  <OrderTotalSum>250.00</OrderTotalSum>
  <!-- ... all other fields ... -->
</OrderNotification>

GET – Query Parameters

כאשר משתמשים ב־GET, הנתונים נשלחים בפרמטרים של כתובת ה־URL. עבור אירועי הזמנה מתקבל בדרך כלל מזהה ייחודי של ההזמנה.

GET Query Parameters – אירועי הזמנה
Parameter Type Description
orderUniqId string (UUID) מזהה הזמנה ייחודי.
uniqId string (UUID) כינוי עבור orderUniqId — אותו ערך, כלול לצורך תאימות.
GET https://yoursite.com/webhooks/takbull
  ?orderUniqId=a1b2c3d4-e5f6-7890-abcd-ef1234567890
  &uniqId=a1b2c3d4-e5f6-7890-abcd-ef1234567890
ב־Webhooks מסוג GET, רק המזהה הייחודי של ההזמנה נמסר. אם יש צורך בפרטי ההזמנה המלאים, יש להשתמש ב־Takbull API כדי לאחזר אותם.

אירוע NewInvoice

כאשר נוצרת חשבונית או מסמך חדש, ניתן לקבל Webhook מסוג NewInvoice.

GET – Query Parameters

GET Query Parameters – NewInvoice
Parameter Type Description
invoiceUniqId string (UUID) מזהה ייחודי של החשבונית או המסמך החדש שנוצר.
GET https://yoursite.com/webhooks/takbull
  ?invoiceUniqId=a1b2c3d4-e5f6-7890-abcd-ef1234567890

POST – JSON Payload

כאשר Request Type = POST ו־ Request Data Type = JSON עבור אירוע NewInvoice, גוף הבקשה הוא אובייקט DocumentVM.

{
  "Id": 501,
  "DocumentNumber": 1042,
  "Mid": "merchant-id",
  "DocumentType": 1,
  "DocumentCreationDate": "2024-06-01T12:00:00",
  "uniqId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "CustomerName": "Israel Israeli",
  "Email": "customer@example.com",
  "Currency": "ILS",
  "TotalPriceWithTax": 295.00,
  "TotalTaxAmount": 45.00,
  "InvoiceStatusCode": 0,
  "InvoiceItems": [
    {
      "Name": "Product A",
      "Quantity": 2,
      "UnitPrice": 100.00,
      "TotalPrice": 200.00,
      "IsTaxteble": true
    }
  ]
}
הצגת טבלת שדות DocumentVM
DocumentVM Fields
Field Type Description
Idintegerמזהה מסמך פנימי.
DocumentNumberintegerמספר מסמך רציף.
Midstringמזהה סוחר.
DocumentTypeintegerסוג מסמך.
DocumentCreationDatestring (ISO 8601)חותמת הזמן שבה המסמך נוצר.
DocumentDatestring | nullתאריך המסמך הרשמי.
uniqIdstring (UUID)מזהה מסמך ייחודי.
InvoiceUniqIdstring (UUID)כינוי עבור uniqId.
CustomerNamestringהשם המלא של הלקוח.
FirstNamestringהשם הפרטי של הלקוח.
LastNamestringשם המשפחה של הלקוח.
Emailstringכתובת האימייל של הלקוח.
PhoneNumberstringמספר הטלפון של הלקוח.
CustomerIdentityNumberstringמספר תעודת הזהות של הלקוח.
AddressLine1stringכתובת הרחוב של הלקוח.
Citystringהעיר של הלקוח.
Countrystringקוד המדינה של הלקוח.
Currencystringקוד מטבע, לדוגמה ILS או USD.
Languagestringשפת המסמך, לדוגמה he או en.
TotalPriceWithTaxdecimalסכום כולל כולל מס.
TotalTaxAmountdecimalסכום המע״מ או המס הכולל.
TotalTaxFreedecimalסכום כולל פטור ממס.
Discountdecimalערך ההנחה שהוחל.
DiscountTypeinteger0 = Amount, 1 = Percentage.
InvoiceStatusCodeintegerמצב דיווח לרשות המסים. 0 = success.
ConfirmationNumberstringמספר אישור מרשות המסים.
PaymentMethodintegerאמצעי התשלום העיקרי שבו נעשה שימוש.
TotalSumPaidInCreditcarddecimal | nullסכום ששולם בכרטיס אשראי.
TotalSumPaidInCashdecimal | nullסכום ששולם במזומן.
TotalSumPaidInCheckdecimal | nullסכום ששולם בצ׳ק.
TotalSumPaidInWIreTransferdecimal | nullסכום ששולם בהעברה בנקאית.
InvoiceItemsarrayשורות פריטים במסמך.
הצגת שדות InvoiceItem
InvoiceItem Fields
Field Type Description
Namestringשם מוצר או שירות.
Quantitydecimalכמות שנמכרה.
UnitPricedecimalמחיר ליחידה, לפני מס.
TotalPricedecimalסך הכול לשורה: Quantity x UnitPrice.
IsTaxteblebooleanהאם מע״מ חל על שורת פריט זו.

סוגי מסמכים ומצבי הזמנה

סוגי מסמכים

Document Types
Value Name Description
1HeshbonitMasחשבונית מס.
2Kabalaקבלה.
3HeshbonitMasKabalaחשבונית מס + קבלה.
4HeshbonitMasZikuiחשבונית מס זיכוי.
5HeshbonitMasZikuiAndKabalaחשבונית מס זיכוי + קבלה.
6KabalaTrumaקבלה על תרומה.
7Heshbonitחשבונית עסקה / חשבונית פרופורמה.
8HeshbonIskaחשבון עסקה.
9Hazmanaאישור הזמנה.
10HatzaatMehirהצעת מחיר.
11TeudatMishloahתעודת משלוח.

מצבי הזמנה

Order Status
Value Name Description
0Pendingהזמנה נוצרה, ממתינה לתשלום.
1Processingהתשלום נמצא בעיבוד.
2Completedהתשלום הצליח.
3Failedהתשלום נכשל.
4Refundedההזמנה הוחזרה / זוכתה.
5Abandonedהלקוח נטש את checkout.

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

אם נקודת הקצה שלכם אינה מחזירה קוד סטטוס HTTP מסוג 2xx, Takbull תנסה לשלוח שוב את ה־Webhook באופן אוטומטי.

Retry Policy
Attempt Delay after previous attempt
Initial delivery שליחה ראשונית ללא עיכוב.
1st retry 15 דקות לאחר הכשל הקודם.
2nd retry 15 דקות לאחר הכשל הקודם.
Final failure ה־Webhook יסומן כ־Failed ולא יבוצעו ניסיונות נוספים.
בסך הכול מתבצעים 3 ניסיונות מסירה: ניסיון ראשוני ועוד 2 ניסיונות חוזרים.

תגובה ל־Webhook והמלצות אבטחה

תגובה תקינה

נקודת הקצה שלכם צריכה להחזיר קוד HTTP מסוג 2xx כאשר ההתראה התקבלה בהצלחה. אם מוחזר קוד שאינו 2xx או שהשרת חורג מזמן ההמתנה, Takbull תתזמן ניסיון חוזר.

  • להחזיר תגובת HTTP 2xx לאחר קבלת ההתראה.
  • להגיב במהירות, בתוך כמה שניות.
  • לבצע עיבוד כבד באופן אסינכרוני ולא לעכב את התגובה.
  • לשמור לוג של מזהה ההזמנה או החשבונית לצורך בדיקות ומעקב.

אימות מקור הבקשה באמצעות Secret

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

ה־User-Agent ושדות התשלום אינם מהווים לבדם הוכחה שהבקשה נשלחה מתקבול. יש להפריד בין אימות מקור הבקשה לבין בדיקת סטטוס התשלום.

המלצות אבטחה

השתמשו ב־HTTPS נקודת הקצה צריכה להיות מאובטחת, במיוחד כאשר מתקבלים פרטי הזמנה, תשלום או מסמך.
אמתו נתונים בצד השרת מומלץ לא להסתמך רק על הנתונים שהתקבלו ב־Webhook אם הפעולה רגישה.
שמרו לוגים שמרו את ה־uniqId, סוג האירוע, זמן קבלה ותוצאת העיבוד.
מנעו עיבוד כפול השתמשו ב־uniqId כדי לוודא שאותה התראה לא יוצרת פעולה כפולה במערכת שלכם.

דוגמאות יישום

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

C# / ASP.NET Core

[HttpPost]
public async Task<IActionResult> TakbullWebhook([FromBody] OrderNotification notification)
{
    if (notification == null)
        return BadRequest();

    // Only process successful payments
    if (notification.StatusCode == 0)
    {
        // TODO: fulfill the order using notification.uniqId
        //       or notification.order_reference
    }

    return Ok();
}

Node.js / Express

app.post('/webhooks/takbull', express.json(), (req, res) => {
  const notification = req.body;

  if (notification.StatusCode === 0) {
    // Payment successful – fulfill the order
    console.log('Order paid:', notification.uniqId);
  }

  res.sendStatus(200);
});

PHP

<?php
$payload = json_decode(file_get_contents('php://input'), true);

if ($payload && $payload['StatusCode'] === 0) {
    // Payment successful – fulfill the order
    error_log('Order paid: ' . $payload['uniqId']);
}

http_response_code(200);

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

  • נקודת הקצה נגישה ציבורית.
  • ה־URL מוגדר בצורה מלאה ונכונה בשדה Hook Address.
  • נבחר Request Type מתאים: GET או POST.
  • נבחר Request Data Type מתאים: JSON, XML או Query.
  • נבחר Event Trigger Type מתאים לתרחיש העסקי.
  • השרת מחזיר HTTP 2xx כאשר ההתראה מתקבלת בהצלחה.
  • העיבוד הכבד מתבצע אסינכרונית ולא חוסם את התגובה ל־Webhook.
  • קיים טיפול במניעת כפילות לפי uniqId.
  • קיימים לוגים לצורך בדיקות, תמיכה ושחזור תקלות.
  • נקודת הקצה עובדת ב־HTTPS.
  • הושלם השלב האחרון של חתימת האבטחה ונשמרו ההגדרות.
  • אם חתימת האבטחה פעילה: המפתח נשמר בשרת בלבד, ומומש אימות לפי מפרט תקבול לפני העיבוד.
  • נבדקו בקשות עם חתימה תקינה, חתימה שגויה וחתימה חסרה; רק בקשה שעברה אימות מפעילה עיבוד.

Webhook שמחבר את Takbull למערכות שלכם בזמן אמת

בעזרת Webhooks ניתן לחבר את Takbull למערכות CRM, מערכות ERP, אתרי תוכן, מערכות דיוור, מערכות ניהול הזמנות וכל מערכת צד שלישי שצריכה לקבל עדכון מיידי על תשלומים, חשבוניות והזמנות.