קבלת Webhook מקארדקום במחשב הפיתוח באמצעות Dev Tunnels

מה הכלי מאפשר?

Microsoft Dev Tunnels מאפשר למפתחים לקבל Webhook מקארדקום ישירות לשרת הפועל במחשב המקומי (localhost).

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

Dev Tunnels מיועד לפיתוח ולבדיקות בלבד, ולא לשימוש בסביבת ייצור.

כיצד זה עובד?

לדוגמה, אם השרת המקומי פועל בכתובת:

http://localhost:5000

Dev Tunnels יפיק כתובת ציבורית ייחודית, לדוגמה:

https://example-5000.devtunnels.ms

כאשר קארדקום תשלח בקשה לכתובת הציבורית, Dev Tunnels יעביר אותה אל השרת המקומי בפורט 5000.

אם נקודת הקצה בקוד היא:

/webhook

כתובת ה־Webhook המלאה תהיה:

https://example-5000.devtunnels.ms/webhook

דרישות מקדימות

לפני שמתחילים, יש לוודא כי:

• Dev Tunnels מותקן במחשב.
• קיים חשבון Microsoft או GitHub לצורך התחברות לכלי.
• השרת המקומי פועל ומוכן לקבל בקשות.
• ידוע באיזה פורט השרת המקומי פועל.
• קיימת בקוד נקודת קצה לקבלת ה־Webhook.
• המחשב מחובר לאינטרנט ומאפשר תקשורת יוצאת לשירות Dev Tunnels.

שלב 1: התקנת Dev Tunnels

במחשב Windows ניתן לפתוח את PowerShell או שורת הפקודה ולהריץ:

winget install Microsoft.devtunnel

בסיום ההתקנה ניתן לוודא שהכלי זמין באמצעות:

devtunnel --version

להוראות התקנה ב־Windows, macOS או Linux ניתן להיעזר במדריך הרשמי של Microsoft.

שלב 2: התחברות לכלי

יש להריץ:

devtunnel user login

לאחר מכן יש להשלים את ההתחברות באמצעות חשבון Microsoft.

ניתן להתחבר גם באמצעות חשבון GitHub:

devtunnel user login -g

ההתחברות נדרשת כדי ליצור ולנהל את המנהרה. האפשרות --allow-anonymous אינה מבטלת את הצורך של המפתח להתחבר לכלי.

שלב 3: הפעלת השרת המקומי

יש להפעיל את הפרויקט ולוודא שהשרת זמין ב־localhost.

לדוגמה:

http://localhost:5000

יש להשתמש בפורט שבו השרת פועל בפועל. אם הפרויקט פועל בפורט אחר, יש להחליף את 5000 בפורט המתאים.

מומלץ לבדוק את נקודת הקצה באופן מקומי לפני יצירת המנהרה, לדוגמה:

http://localhost:5000/webhook

שלב 4: יצירת Dev Tunnel

כאשר השרת המקומי פעיל, יש לפתוח חלון נוסף של PowerShell או שורת הפקודה ולהריץ:

devtunnel host -p 5000 --allow-anonymous

פירוט הפקודה:

• devtunnel host – יצירת מנהרה מהמחשב המקומי.
• -p 5000 – הפניית התעבורה לפורט המקומי 5000.
• --allow-anonymous – מאפשר למערכת חיצונית, כמו קארדקום, לגשת לכתובת ללא התחברות לחשבון Microsoft.

בסיום ההרצה תוצג כתובת HTTPS ציבורית ייחודית, לדוגמה:

Hosting port 5000 at https://example-5000.devtunnels.ms/

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

שלב 5: הגדרת כתובת ה־Webhook

יש להעתיק את כתובת ה־HTTPS שהתקבלה ולהוסיף אליה את הנתיב של נקודת הקצה בקוד.

לדוגמה:

https://example-5000.devtunnels.ms/webhook

את הכתובת המלאה יש למסור לקארדקום ככתובת ה־Webhook בהתאם לאופן המימוש שבו משתמשים, למשל במסגרת בקשת דף פרופיל נמוך.

חשוב לוודא כי:

• הכתובת מתחילה ב־https://.
• נתיב נקודת הקצה מופיע במלואו.
• אין להשתמש בכתובת localhost ככתובת ה־Webhook.
• המנהרה והשרת המקומי פעילים בזמן שליחת הבקשה.

הגדרת כתובת ה־Webhook בממשק JSON של קארדקום:

ביצירת הדף לתשלום - Create a new Iframe \ Redirect page
יש למלא את הכתובת בשדה WebHookUrl:

שלב 6: ביצוע בדיקה

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

לאחר מכן יש לבדוק:

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

אין להסתמך רק על פתיחת כתובת המנהרה בדפדפן. Webhook עשוי להישלח בשיטת בקשה שונה מבקשת GET רגילה של דפדפן.

צפייה בבקשות שהתקבלו

בעת הפעלת המנהרה, הכלי עשוי להציג גם כתובת לבדיקת התעבורה, המסומנת כ־Inspect URL.

באמצעות כתובת זו ניתן לצפות בבקשות שעברו במנהרה ולבדוק בין היתר:

• מועד שליחת הבקשה.
• כתובת היעד.
• שיטת הבקשה.
• הכותרות שנשלחו.
• תוכן הבקשה.
• התגובה שהוחזרה מהשרת המקומי.

האפשרות מסייעת להבחין בין שני מצבים:

• קארדקום לא שלחה בקשה או שהבקשה לא הגיעה למנהרה.
• הבקשה הגיעה למנהרה, אך לא טופלה כראוי בקוד המקומי.

עצירת המנהרה

כדי להפסיק את המנהרה, יש לעבור לחלון שבו היא פועלת וללחוץ:

Ctrl+C

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

דגשים בנושא אבטחה

השימוש ב־--allow-anonymous מאפשר לקארדקום לשלוח בקשות למנהרה ללא תהליך התחברות, אך גם הופך את הכתובת לנגישה מהאינטרנט למי שמכיר או מצליח לאתר אותה.

לכן:

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

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

תקלות נפוצות

לא התקבלה בקשה בקוד

יש לוודא כי:

• השרת המקומי פועל.
• המנהרה עדיין פעילה.
• נבחר הפורט הנכון.
• כתובת ה־Webhook כוללת את הנתיב המלא.
• כתובת המנהרה המעודכנת הוגדרה בבקשה.
• נקודת הקצה תומכת בשיטת הבקשה שנשלחת.
• אין שגיאה בקוד בעת קליטת הבקשה.

התקבלה שגיאת Connection Refused

השגיאה עשויה להעיד שהמנהרה פעילה, אך אין שרת שמאזין בפורט שהוגדר.

יש לבדוק באיזה פורט הפרויקט פועל ולהריץ מחדש, לדוגמה:

devtunnel host -p PORT --allow-anonymous

יש להחליף את PORT במספר הפורט בפועל.

מופיע מסך התחברות של Microsoft

ככל הנראה המנהרה הופעלה ללא הרשאת גישה אנונימית.

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

devtunnel host -p 5000 --allow-anonymous

הכתובת עבדה בעבר וכעת אינה זמינה

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

יש להפעיל אותה מחדש ולעדכן את כתובת ה־Webhook אם התקבלה כתובת חדשה.

הבקשה מופיעה בכלי הבדיקה אך לא בקוד

יש לבדוק:

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

הכלי אינו מזוהה לאחר ההתקנה

יש לסגור ולפתוח מחדש את PowerShell או שורת הפקודה ולבדוק:

devtunnel --version

אם התקלה נמשכת, יש לוודא שההתקנה הסתיימה בהצלחה ושמיקום הכלי נוסף למשתנה PATH.

סיכום

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

הפקודה המרכזית:

devtunnel host -p 5000 --allow-anonymous

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