Webhooks

מדריך זה מתעד איך ShipOS משתמש ב-webhooks לתקשורת בזמן אמת עם חנויות WooCommerce, כולל כתובות URL של webhooks, פורמטי payload והזרקת שדה is_virtual.

סקירה

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

Webhooks של WooCommerce

ShipOS רושם שלושה webhooks עם חנות WooCommerce בזמן תהליך ההגדרה:

פורמט URL של Webhook

נקודות קצה webhook של ShipOS עוקבות אחרי התבנית:

https://app.shipos.co.il/api/wp/webhooks/{wp_site_id}/order_created
https://app.shipos.co.il/api/wp/webhooks/{wp_site_id}/order_updated
https://app.shipos.co.il/api/wp/webhooks/{wp_site_id}/order_deleted

• {wp_site_id} הוא המזהה הייחודי של חנות WooCommerce במסד הנתונים של ShipOS (מטבלת wp_sites).

הערה: נקודות קצה webhook אלה לא דורשות middleware אימות. ה-wp_site_id ב-URL מזהה את החנות, ה-payload של ה-webhook מאומת באמצעות סוד ה-webhook של WooCommerce.

הזרקת שדה is_virtual

תוסף WooCommerce של ShipOS מתאים את ה-payload של ה-webhook על ידי הזרקת שדה is_virtual לכל פריט בהזמנה. זה קריטי לקביעה אם הזמנה דורשת משלוח פיזי.

איך זה עובד

1. תוסף WooCommerce מתחבר לפילטר woocommerce_webhook_payload.
2. לכל פריט בהזמנה, הוא בודק אם המוצר וירטואלי.
3. הוא מוסיף "is_virtual": true או "is_virtual": false לכל פריט ב-payload.

למה זה חשוב

• כל הפריטים וירטואליים: ההזמנה לא דורשת משלוח פיזי (למשל מוצרים דיגיטליים, כרטיסי מתנה).
• חלק מהפריטים וירטואליים: רק פריטים פיזיים צריך לשלוח; פריטים וירטואליים מוחרגים מחישובי משקל/חבילות.
• אף פריט לא וירטואלי: משלוח סטנדרטי חל על כל הפריטים.

לוגיקת עיבוד

IF all line_items have is_virtual = true
  → Skip shipment creation (no physical delivery needed)
ELSE
  → Create shipment for physical items only

⚠️ אזהרה: אם שדה is_virtual חסר מ-payload ה-webhook, ShipOS מתייחס לכל הפריטים כפיזיים. ודאו שתוסף WooCommerce מותקן ופעיל כדי ששדה זה יוזרק.

רישום Webhook

רישום אוטומטי

Webhooks נרשמים אוטומטית בזמן אשף ההגדרה של תוסף ShipOS:

1. התוסף מתחיל OAuth עם WooCommerce לקבלת consumer key/secret.
2. באמצעות WooCommerce REST API, ShipOS רושם את שלושת ה-webhooks.
3. כל webhook מוגדר עם:
   • נושא: order.created, order.updated, order.deleted
   • URL מסירה: https://app.shipos.co.il/api/wp/webhooks/{wp_site_id}/{event}
   • סוד: סוד משותף לאימות payload

רישום מחדש ידני

אם webhooks מפסיקים לעבוד (למשל אחרי העברת אתר), רשמו אותם מחדש:

1. בלוח הבקרה של ShipOS (בתוך ניהול WP), עברו להגדרות.
2. לחצו רישום מחדש של Webhooks.
3. ShipOS ימחק webhooks ישנים וייצור חדשים.

אימות Webhook

WooCommerce חותם payloads של webhook עם חתימת HMAC-SHA256 באמצעות סוד ה-webhook.

כותרת אימות

X-WC-Webhook-Signature: base64(hmac-sha256(payload, secret))

לוגיקת אימות

$signature = base64_encode(
    hash_hmac('sha256', $payload_body, $webhook_secret, true)
);

if ($signature !== $received_signature) {
    // Reject the request
    return response('Invalid signature', 401);
}

הערה: ShipOS מטפל באימות חתימה אוטומטית. מידע זה מיועד למפתחים שבונים אינטגרציות מותאמות.

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

ל-WooCommerce יש לוגיקת ניסיון חוזר מובנית למסירות webhook כושלות:

אחרי 5 ניסיונות כושלים, ה-webhook מסומן כמושבת וצריך להיות מופעל מחדש ידנית.

💡 טיפ: אם webhooks נכשלים באופן עקבי, בדקו ששרת ShipOS נגיש מחנות WooCommerce. סיבות נפוצות כוללות כללי חומת אש, בעיות תעודת SSL או חסימות Cloudflare.

פתרון בעיות Webhooks

צעדים הבאים

• נקודות קצה משלוחים - יצירת משלוחים מנתוני webhook
• סקירת API - אימות ושימוש כללי
• נקודות קצה רישיונות - ניהול רישיונות