איך לבנות אינטגרציות משלכם באמצעות Webhooks

הכלל „שלח ל-Webhook” מאפשר לכם להפוך לאוטומטי את שליחת הפוסטים החדשים מעדכוני RSS אל נקודת הקצה של ה-Webhook שהגדרתם, מיד כשהם זמינים. תוכלו גם לדייק אילו פוסטים יישלחו באמצעות הגדרת מילות מפתח לסינון. כשפוסט חדש עומד בקריטריונים שלכם, הוא יישלח לנקודת הקצה כבקשת POST בפורמט JSON.

מבנה מטען JSON

כל בקשת POST שנשלחת ל-Webhook שלכם תכלול שני רכיבים עיקריים: post ו-feed.

הבקשה כוללת גם מטא-נתונים לזיהוי הודעת ה-Webhook. השדה version מציין איזו גרסה של ממשק ה-API של Feeder ל-Webhook נשלחת. הערך קבוע ל-2023-06-26, והוא יתעדכן אם יתבצעו שינויים שאינם תואמים לאחור.

{
  "version": "2023-06-26",
  "message_id": "a unique UUID for this message, will be constant during retries",
  "feed": { ... },
  "post": { ... }
}

הרכיב post מכיל מידע על הפוסט המסוים:

{
  "id": "The unique identifier of the post",
  "title": "The title of the post",
  "url": "The URL where the post can be accessed",
  "published": "The date and time when the post was published",
  "content": "The content of the post",
  "audio_url": "link to mp3 attached to post (if present)",
  "image_url": "link to image attached to post (if present)
}

שימו לב: הערך של published יהיה null אם עדכון ה-RSS לא ציין תאריך פרסום תקין.

הרכיב feed מספק מידע על העדכון שממנו מגיע הפוסט:

{
  "id": "The unique identifier of the feed",
  "source_url": "The URL of the source, for example RSS/Atom feed URL",
  "public_url": "The source's self identified public URL",
  "title": "The title of the feed",
  "favicon": "The URL of the feed's favicon"
}

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

מנגנון ניסיונות חוזרים

אם בקשה נכשלת, Feeder מנסה לשלוח אותה שוב באופן אוטומטי. אם בקשת POST אינה מקבלת קוד תגובת HTTP בטווח 200 עד 399, ננסה לשלוח אותה מחדש לפי לוח זמנים מוגדר, בשניות:

• ניסיון חוזר 1: אחרי 5 שניות
• ניסיון חוזר 2: אחרי 30 שניות
• ניסיון חוזר 3: אחרי 60 שניות
• ניסיון חוזר 4: אחרי 5 דקות
• ניסיון חוזר 5: אחרי 10 דקות
• ניסיון חוזר 6: אחרי 30 דקות
• ניסיון חוזר 7: אחרי 30 דקות
• ניסיון חוזר 8: אחרי 30 דקות

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

איתור שגיאות

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

שם תוכלו לראות פרטים נוספים על ה-Webhooks שנכשלו.

הגדרת ה-Webhook

כדי להגדיר את ה-Webhook:

1. עברו אל הדף כללים.
2. צרו כלל חדש.
3. הוסיפו שם, עדכונים וקריטריונים.
4. בקטע „מה אמור לקרות?”, בחרו „שלח ל-Webhook”.
5. הזינו את כתובת ה-Webhook שלכם בשדה הטקסט המתאים.
6. כדי לוודא שהכול הוגדר כראוי, תוכלו ללחוץ על הכפתור „שלח הודעת ניסיון” כדי לשלוח הודעת בדיקה לנקודת הקצה שלכם. שימו לב, זו רק בדיקה, ואם היא נכשלת היא לא תפעיל את מנגנון הניסיונות החוזרים. כמו כן, כדי לשלוח את הודעת הבדיקה, צריך להיות לפחות עדכון אחד עם פוסטים שנוסף לחשבון שלכם.

אבטחה: אימות חתימות Webhook

כדי לוודא שבקשות Webhook נכנסות אכן נשלחו מ-Feeder ולא שונו, תוכלו לאמת את הסוד שנוצר לכל Webhook. כל בקשת Webhook תכלול כותרת X-Feeder-Signature ובה חתימת HMAC-SHA256 של גוף הבקשה.

איך זה עובד

1. בהגדרות הכלל, הפעילו את האפשרות „מתקדם”. בשדה „סוד ה-Webhook” תופיע מחרוזת.
2. כש-Feeder שולח Webhook לנקודת הקצה שלכם, הוא מחשב גיבוב HMAC-SHA256 של גוף בקשת ה-JSON, באמצעות הסוד שלכם כמפתח.
3. החתימה שנוצרה נשלחת בכותרת X-Feeder-Signature, עם הקידומת sha256=. לדוגמה:

   X-Feeder-Signature: sha256=a1b2c3d4e5f6...

4. בשרת שלכם, חשבו מחדש את אותו גיבוב HMAC-SHA256 באמצעות גוף הבקשה הגולמי והעותק שלכם של הסוד, ואז השוו אותו לערך שבכותרת.

למה להשתמש בזה?

• אותנטיות: מאשרת שהבקשה נשלחה מ-Feeder ולא מצד שלישי.
• שלמות: מבטיחה שהמטען לא שונה במהלך השליחה.

אימות החתימה

כדי לאמת:

1. קראו את גוף הבקשה הגולמי כמחרוזת, בלי לנתח אותו קודם.
2. חשבו את HMAC-SHA256 של המחרוזת באמצעות הסוד שלכם.
3. השוו את החתימה שחישבתם לערך שבכותרת X-Feeder-Signature, באמצעות השוואה בטוחה מבחינת זמן כדי למנוע מתקפות תזמון.

דוגמה: Node.js ‏(Express)

const crypto = require("crypto");

const WEBHOOK_SECRET = process.env.FEEDER_WEBHOOK_SECRET;

function verifyFeederSignature(req, res, next) {
  const signature = req.headers["x-feeder-signature"];
  if (!signature) {
    return res.status(401).send("Missing signature");
  }

  const expectedSignature =
    "sha256=" +
    crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.body).digest("hex");

  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  next();
}

// Important: use express.raw() so req.body is the raw string, not parsed JSON
app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  verifyFeederSignature,
  (req, res) => {
    const payload = JSON.parse(req.body);
    // Handle the webhook payload
    console.log("Received verified webhook:", payload);
    res.sendStatus(200);
  }
);

חשוב: כדי לאמת את החתימה, חובה לגשת לגוף הבקשה הגולמי. אם סביבת העבודה שלכם מנתחת את גוף ה-JSON לפני חישוב ה-HMAC, המחרוזת שתיווצר מחדש עשויה להיות שונה מהמקור והחתימה לא תתאים. ב-Express, השתמשו ב-express.raw({ type: "application/json" }) בנתיב ה-Webhook, כפי שמוצג למעלה.

יש עוד שאלות?

יש לכם שאלות? כתבו לנו לכתובת support@feeder.co.