Webhook מה זה: מה זה וובהוק ואיך מחברים אותו
Webhook מה זה? וובהוק הוא כתובת שהמערכת קוראת לה ברגע שיש אירוע, בלי לבדוק כל הזמן. ההבדל מקריאת API, דוגמאות לעסק, ואיך יוצרים webhook ב-Pingmee.
וובהוק (webhook) הוא כתובת אינטרנט שהמערכת קוראת לה ברגע שמשהו קרה, למשל כשנפתחת שיחה או כשמגיעה הודעה. במקום שתבדקו כל כמה דקות אם יש חדש, האירוע נדחף אל הכתובת שלכם.
Webhook מה זה, ומה ההבדל מקריאת API
קריאת API היא בקשה שאתם שולחים. אתם פונים לשרת, והוא עונה עם מה שביקשתם. אם רוצים לדעת על שיחה חדשה, צריך לשאול שוב ושוב.
וובהוק הוא הכיוון השני. אתם רושמים כתובת וסוג אירוע. כשהאירוע קורה, Pingmee פונה אל הכתובת הזו. אתם לא שולחים את הבדיקה. המערכת שולחת את ההודעה על האירוע.
שתי דוגמאות בעסק
ליד חדש נכנס ל-CRM
נרשמים לאירוע conversationCreated (שיחה חדשה) או messageCreated (הודעה חדשה). הכתובת שרשמתם היא של המערכת שלכם, למשל שירות שפותח רשומה ב-CRM. התיעוד מגדיר את ההרשמה: כתובת ואירוע, ובתשובה מזהה. הוא לא מפרסם את שדות ה-JSON שמגיעים אל הכתובת, אז את גוף ההודעה בודקים מול קריאה אמיתית אחרי היצירה, לא לפי ניחוש.
עדכון הזמנה יוצא בוואטסאפ
כאן הכיוון הפוך. החנות, או מערכת ההזמנות, מפעילה workflow ב-Pingmee. הקריאה היא POST https://workflows.pingmee.co.il/workflows/{workflowId}/trigger. בגוף חובה phoneNumberId (מזהה המספר של העסק) ו-customerPhoneNumberId. אפשר לצרף אובייקט triggerData, למשל מספר הזמנה, וה-workflow קורא אותו בביטוי. המזהה בנתיב צריך להיות מקודד ל-URL.
הקריאה הזו פותחת שיחה מצד העסק. לכן צומת הוואטסאפ הראשון ב-workflow צריך להיות תבנית שאושרה, לא הודעה חופשית. ה-workflow נשמר כבוי ביצירה, ומפעילים אותו ב-PUT עם { "isActive": true }. המקור: Trigger Workflow.
איך יוצרים webhook ב-Pingmee
הנקודות הן על https://api.pingmee.co.il. בכל קריאה צריך שני ערכים מתוך Pingmee, בהגדרות, כלים למפתחים: ה-personal token נשלח בכותרת Cookie, ומפתח ה-API בכותרת x-api-key. עמוד המבוא אומר לשלוח Cookie ולא כותרת Authorization. לכל עסק יש מפתחות משלו. Authentication & Headers.
- יוצרים הרשמה: POST /webhook. בגוף JSON שני שדות חובה: url (הכתובת שתקבל את האירוע) ו-event.
- הערכים המתועדים ליצירה: conversationCreated (שיחה חדשה), tagChanged (תגיות השיחה עודכנו), statusChanged (סטטוס השיחה עודכן), messageCreated (הודעות חדשות). תשובת 200 כוללת id.
- כדי לראות מה רשום: GET /webhook. חוזרת רשימה, ולכל פריט id, url ו-event.
- כדי למחוק: DELETE /webhook/{webhookId}. את המזהה מקודדים בנתיב. אם הוא לא נמצא חוזר 404.
יש פער בתיעוד שכדאי לבדוק לפני שמסתמכים על השם הרביעי. ביצירה הערך הוא messageCreated. בסכמה של ה-GET הערך הרביעי רשום messageUpdated, אבל מפת התיאורים של אותו שדה עדיין אומרת messageCreated ו״Messages Created״. המקורות: Create Webhook, Get Webhooks, Delete Webhook.
Workflow בתוך Pingmee, בלי כתובת חיצונית
אפשר גם להגיב לאירוע בתוך Pingmee, בלי שרת משלכם. טריגר pingmeeTrigger מאזין להודעה מהלקוח, למשל Messages Created או New Conversation Started, וממשיך לצמתים בלוח. זה לא אותה קריאה כמו POST /webhook. ה-webhook מוסר אירוע לכתובת חיצונית. ה-workflow רץ אצל Pingmee.
בלי קוד, אותו חיבור קיים גם ב-Make וב-n8n. ב-n8n מתועדת פעולה בשם Subscribe to message/conversation webhooks, ורק כש-n8n מותקן אצלכם, לא ב-n8n Cloud. המדריך: לחבר וואטסאפ ל-Make ול-n8n. תיעוד ה-API: מרכז התיעוד.
למה הרשמה או שליחה נכשלות
- 401. חסרים Cookie או x-api-key, או שהערכים לא תקינים. עמוד המבוא אומר שבלי שניהם הבקשה נדחית.
- 400 ביצירה. חסר url או event, או שהאירוע אינו אחד מארבעת הערכים של היצירה.
- 404 במחיקה. המזהה לא קיים, או שלא קודד בנתיב.
- Workflow כבוי. יצירה שומרת isActive: false עד שמפעילים בנפרד.
- תבנית. הפעלה שפותחת שיחה בלי תבנית מאושרת בצומת הוואטסאפ הראשון לא עומדת בכלל שמתועד ב-Trigger.
- 409 בעדכון גרף. אם שולחים את הגרף בלי lastModified מה-GET או מהיצירה האחרונים, ה-API מחזיר 409.
התיעוד לא מתאר ניסיונות שליחה חוזרים, חתימה על הבקשה אל הכתובת שלכם, או את צורת ה-JSON של האירוע. אלה לא חלק מההגדרה בעמודים למעלה.
לאן ממשיכים
- אוטומציה עם Make ו-n8n, כולל שליחת הודעה ותבנית.
- CRM אוטומטי לעסק חכם.
- שירות לקוחות בוואטסאפ, כשהמענה נשאר בתיבה של הצוות.
- בוטים חכמים לעסק.
שאלות נפוצות
Webhook מה זה?
וובהוק הוא כתובת אינטרנט שהמערכת קוראת לה ברגע שמשהו קרה, למשל שיחה חדשה או הודעה חדשה. במקום לשאול את השרת שוב ושוב אם יש חדש, האירוע נדחף אל הכתובת. ב-Pingmee יוצרים את זה ב-POST /webhook עם url ו-event. https://docs.pingmee.co.il/api-reference/webhook/create
מה ההבדל בין וובהוק לקריאת API?
קריאת API היא בקשה שאתם שולחים, והשרת עונה. וובהוק הוא הכיוון השני: אתם רושמים כתובת, ו-Pingmee פונה אליה כשיש אירוע. https://pingmee.co.il/blogs/אוטומציה-בפיתוח/הכוח-של-Webhooks-בעסק/
אילו אירועים אפשר לרשום ב-webhook של Pingmee?
ביצירה מתועדים conversationCreated, tagChanged, statusChanged ו-messageCreated. GET מחזיר id, url ו-event. בסכמה של ה-GET הערך הרביעי רשום messageUpdated, ובמפת התיאורים של אותו שדה עדיין כתוב messageCreated. כדאי לבדוק איזו מחרוזת נשמרת. מחיקה היא DELETE /webhook/{webhookId} עם מזהה מקודד בנתיב. https://docs.pingmee.co.il/api-reference/webhook/create https://docs.pingmee.co.il/api-reference/webhook/get
איך שולחים עדכון הזמנה בוואטסאפ מתוך מערכת חיצונית?
המערכת החיצונית קוראת ל-POST /workflows/{workflowId}/trigger על workflows.pingmee.co.il, עם phoneNumberId ו-customerPhoneNumberId, ואפשר triggerData. זו פתיחת שיחה מצד העסק, ולכן צומת הוואטסאפ הראשון צריך תבנית מאושרת. ה-workflow נוצר כבוי עד PUT עם isActive true. https://docs.pingmee.co.il/api-reference/workflows/trigger
למה יצירת webhook מחזירה 401 או 400?
401 כשחסרים ה-Cookie עם ה-personal token או הכותרת x-api-key, או שהם לא תקינים. 400 כשחסר url או event, או שהאירוע אינו אחד מארבעת ערכי היצירה. שני הערכים נמצאים ב-Pingmee בהגדרות, כלים למפתחים. https://docs.pingmee.co.il/api-reference/webhook/create