מדריך אינטגרציית Webhook

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

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

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

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

כאשר 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
}

כאשר 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, הנתונים נשלחים בפרמטרים של כתובת ה־URL. עבור אירועי הזמנה מתקבל בדרך כלל מזהה ייחודי של ההזמנה.

GET https://yoursite.com/webhooks/takbull
  ?orderUniqId=a1b2c3d4-e5f6-7890-abcd-ef1234567890
  &uniqId=a1b2c3d4-e5f6-7890-abcd-ef1234567890

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

GET – Query Parameters

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
    }
  ]
}

סוגי מסמכים

מצבי הזמנה

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

תגובה תקינה

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

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

המלצות אבטחה

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.