איך זה עובד
כשאתה מפרסם מאמר ב-Sorank, אנו שולחים בקשת POST עם מטען JSON מובנה ל-URL שהגדרת. נקודת הקצה או כלי האוטומציה שלך יכולים לעבד את המטען וליצור את הפוסט בבלוג שלך, באתר מותאם אישית או בכל כלי אחר שמקבל בקשות HTTP נכנסות.⚠️ חשוב: ה-webhook רק שולח את הנתונים, אתה מפרסם אותם
זה הדבר הכי חשוב להבין על מחבר ה-Webhook. מהצד שלנו, Sorank אורזת את כל מה שצריך בתוך ה-JSON (כותרת, slug, גוף HTML מלא, מטא-תיאור, תמונות, שפה ועוד) ושולחת ל-URL שלך. ברגע שה-JSON נשלח בהצלחה, Sorank מסמנת את המסירה כ-success. סטטוס “success” זה מאשר רק דבר אחד: הנתונים יצאו מ-Sorank ונקודת הקצה שלך קיבלה אותם. אין לנו דרך לדעת מה קורה אחר כך בצד שלך. איננו יכולים לזהות אם הקוד שלך אכן קרא את ה-JSON, מיפה את השדות נכון, או פרסם את המאמר באתר שלך. במילים אחרות, ה-webhook הוא רק מנגנון מסירה של הנתונים. קבלתם, ניתוחם ופרסומם ל-CMS שלך היא כולה באחריותך. אם המאמר לא מופיע בבלוג שלך למרות ש-Sorank מציגה “success”, הבעיה כמעט תמיד היא באופן שבו האינטגרציה שלך תופסת ומטפלת במטען, ולא במסירה עצמה.שלב 1: פתיחת אינטגרציית ה-Webhook
- לחץ על תמונת הפרופיל בפינה הימנית העליונה ובחר Settings.
- פתח את לשונית Integrations.
- גלול לכרטיס Webhook ולחץ על Connect your website.
שלב 2: הגדרת נקודת הקצה שלך
- הדבק את ה-URL של היעד לתוך שדה Webhook URL (למשל, catch hook של Zapier, webhook של Make, או נקודת קצה של שרת משלך).
- לחלופין, הוסף Secret token אם נקודת הקצה שלך דורשת אימות. Sorank תכלול אותו כאסימון
BearerבכותרתAuthorizationכדי שהשרת שלך יוכל לוודא שהקריאה באה מ-Sorank. - לחץ על Test כדי לשלוח מטען לדוגמה (סוג האירוע
webhook.test) ולוודא שנקודת הקצה שלך מגיבה נכון. - לחץ על Save webhook להפעלת האינטגרציה.
פרטי בקשת HTTP
כל webhook ש-Sorank שולחת לנקודת הקצה שלך פועל לפי אותו חוזה HTTP. הנה מה שהשרת שלך יקבל:- Method:
POST - Content-Type:
application/json - User-Agent:
SORANK-Webhook/1.0 - Authorization:
Bearer {webhook_secret}(אופציונלי, נשלח רק אם הגדרת סוד באינטגרציה).
User-Agent לזיהוי תעבורת Sorank בלוגים שלך, וודא את כותרת Authorization בצד שלך כדי לוודא שהבקשה באה מ-Sorank ולא ממוקד לא ידוע.
מבנה מטען ה-Webhook
Sorank משדרת שני סוגי אירועי webhook. שניהם חולקים את אותו מעטפת עליונה (event, delivery_id, timestamp, article) כך שהאינטגרציה שלך צריכה רק להסתעף על שדה event כדי לנתב את המטען.
Event: article.published
מופעל בכל פעם שאתה מפרסם מאמר מ-Sorank. זהו האירוע שנקודת הקצה של הייצור שלך צריכה לעבד כדי ליצור את הפוסט ב-CMS או להפעיל את זרימת האוטומציה שלך.Event: webhook.test
מופעל כשאתה לוחץ על כפתור Test ב-Sorank כדי לוודא שנקודת הקצה שלך נגישה. המטען משתמש בערכי דמה (id כולו אפסים, featured_image מושמט, images ריק) כך שהאינטגרציה שלך יכולה בבטחה להתעלם ממנו או להשתמש בו כדי לאשר קישוריות בלי ליצור פוסט אמיתי.הפניית שדות
- event, סוג האירוע.
article.publishedאוwebhook.test. הסתעף על שדה זה כדי לנתב את המטען. - delivery_id, UUID ייחודי לכל ניסיון מסירה. שמור אותו בצד שלך למניעת כפילויות בעת ניסיונות חוזרים ולהגנה מפני פרסום כפול.
- timestamp, חותמת זמן ISO 8601 UTC של מתי האירוע שודר.
- article.id, מזהה ייחודי של המאמר ב-Sorank.
- article.title, ה-H1 / כותרת המאמר.
- article.slug, slug ידידותי ל-URL, אותיות קטנות עם מקפים.
- article.meta_description, מטא-תיאור SEO, מוכן להכנסה בתגית
<meta name="description">שלך. - article.focus_keyphrase, מילת המפתח המרכזית של המאמר.
- article.content, גוף המאמר המלא ב-HTML, כולל כותרות, פסקאות, רשימות ותגיות תמונה inline.
- article.featured_image, אובייקט תמונת שער עם
url,altו-placement. מוצג רק באירועיarticle.published. - article.images, מערך של תמונות נוספות בגוף. לכל רשומה יש
url,altו-placement. יכול להיות ריק. - article.word_count, סך המילים של גוף המאמר.
- article.keyword, זהה למילת המפתח המרכזית, נשמר כשדה נפרד לצורך תאימות לאחור.
- article.language, תג שפה לפי BCP 47 (למשל
en-US,fr-FR).
מקרי שימוש נפוצים
- Zapier: השתמש בטריגר “Catch Hook” כדי להעביר מאמרים לאלפי אפליקציות כמו WordPress, Notion, Airtable או Google Sheets.
- Make: השתמש במודול Webhooks כדי לבנות אוטומציות פרסום מותאמות בשלבים מרובים.
- n8n: חבר צומת Webhook לזרימה שיוצרת את הפוסט ב-CMS ללא ראש או במערכת ניהול פנימית.
- Backend מותאם: שלח מאמרים ישירות ל-API משלך לפרסום באתר מקודד ידנית, ב-CMS ללא ראש כמו Sanity או Strapi, או בכל כלי פנימי.
טיפים
- תמיד לחץ על Test לפני השמירה כדי לוודא שנקודת הקצה שלך מקבלת את הבקשה ומחזירה תגובת 2xx.
- הסתעף על שדה
eventבצד השרת כדי שקריאותwebhook.testלעולם לא ייצרו פוסטים אמיתיים. - השתמש ב-
delivery_idכמפתח אידמפוטנטיות כדי להימנע מפרסום אותו מאמר פעמיים בניסיונות חוזרים. - שמור על Secret token פרטי, ודא את כותרת
Authorizationבכל בקשה, וסובב את הסוד באופן קבוע. - השתמש בנקודת קצה HTTPS כדי לשמור על נתוני המאמר מאובטחים במעבר.
- ברגע שחוברת, כל מאמר שיפורסם ב-Sorank יישלח אוטומטית ל-URL של ה-webhook שלך.
🔄 מדוע המאמרים שלך עלולים לא להופיע (סיבות לכשל)
מכיוון שה-webhook רק מוסר את הנתונים, “success” ב-Sorank אינו מבטיח שהמאמר חי באתר שלך. כשמשהו משתבש, זה כמעט תמיד בצד המקבל. הנה הסיבות הנפוצות ביותר וכיצד לתקן אותן.סיבות בצד האינטגרציה שלך
- מפתח ה-API של ה-CMS שלך הוא לקריאה בלבד ולא לקריאה וכתיבה, זו אחת הבעיות הנפוצות ביותר. אם לאישורים שהקוד שלך משתמש בהם לכתיבה ל-CMS (Sanity, Strapi, Contentful, או כל backend ללא ראש) יש רק הרשאות view / read, נקודת הקצה שלך תקבל את ה-JSON אך תיכשל בשקט ביצירת הפוסט. צור מפתח עם הרשאות write ועדכן אותו באינטגרציה שלך.
- הקוד שלך מקבל את ה-JSON אך לא דוחף אותו ל-CMS, קבלת המטען היא רק חצי מהעבודה. ודא שנקודת הקצה שלך אכן ממפה את שדות Sorank ויוצרת את הפוסט ב-CMS או במסד הנתונים שלך. תעד את המטען הנכנס וודא שקריאת הפרסום שלך רצה ומצליחה.
- מיפוי שדות שגוי, אם הקוד שלך מצפה לשמות שדות שונים מאלה שבמטען, הפוסט עשוי להיווצר ריק או להידחות. בדוק שוב שאתה קורא
article.title,article.slug,article.contentוכו’, בדיוק כפי שמתועד למעלה. - נקודת הקצה שלך מחזירה 2xx אך זורקת שגיאה אחר כך, אם אתה מאשר את הבקשה לפני עיבודה באופן אסינכרוני, כשל מאוחר יותר בלוגיקת הפרסום שלך לא יהיה גלוי ל-Sorank. בדוק את לוגי השרת שלך כדי לתפוס את אלה.
סיבות בצד המסירה
- נקודת הקצה של ה-webhook שלך לא מגיבה יותר (שרת לא מקוון), החזר את השרת שלך לפעולה וודא שה-URL מגיב כרגיל.
- ה-URL של ה-webhook השתנה אך לא עודכן ב-Sorank, עדכן את ה-URL בהגדרות האינטגרציה של Sorank.
- יצרת מחדש את סוד ה-webhook בצד שלך, עדכן את הסוד ב-Sorank כך שיתאים לזה שהשרת שלך מצפה לו כעת בכותרת
Authorization. - נקודת הקצה שלך מחזירה שגיאה ש-Sorank לא יכולה לפרש, בדוק את לוגי השרת שלך כדי לזהות את הבעיה, ואז תקן אותה בצד ה-webhook שלך.
- חומת אש בשרת שלך חוסמת את הבקשות שלנו, הכנס את כתובות ה-IP של Sorank לרשימת ההיתר בחומת האש שלך, או אפשר את ה-User-Agent
SORANK-Webhook/1.0. - נקודת הקצה שלך לוקחת יותר מ-30 שניות להגיב, בצע אופטימיזציה לנקודת הקצה כדי שתגיב מהר יותר, או אשר את הבקשה מיד ועבד אותה באופן אסינכרוני.