הגדרת אינטגרציות Webhook של Contentful: ISR, Cache, Deployment

מדוע התראות Push הפכו לסטנדרט עבור Contentful

תארו לעצמכם: אתם מפרסמים פוסט בבלוג דרך Contentful, אבל הוא מופיע באתר רק 15 דקות מאוחר יותר — כי הבנייה רצה פעם בשעה. או אחרי עריכת הכותרת, כל העמודים נבנים מחדש למרות שרק פאנל אחד השתנה. אלה תרחישים טיפוסיים שבהם webhooks הם הכרחיים. Webhooks פותרים את הבעיה באופן מיידי: שינויי תוכן (פרסום, ארכוב, מחיקה) מפעילים את ה-handler שלכם. זהו הבסיס לפעולה חלקה של אתרי SSR/ISR. Webhook אחד יכול לחסוך עד 90% מתעבורת ה-API על ידי ביטול ה-polling, ולהפחית עלויות API עד $500 לחודש. אנו מגדירים אינטגרציות webhook במפתח מלא — מבנייה סטטית פשוטה ועד לפסילת עמודים ממוקדת. הניסיון שלנו בהגדרת webhooks של Contentful כולל מעל 50 אינטגרציות מוצלחות, כל אחת בעלות הגדרה של $200–$1500 וחיסכון אופייני של $500 לחודש.

יתרונות Webhooks על פני Polling

בדיקת ה-API של Contentful כל 10 שניות יוצרת עומס נוסף והשהיה. Webhooks, לעומת זאת, דורשים בקשות קבועות: השרת עצמו מודיע לכם על שינויים. זה מפחית את עומס ה-API פי 10 ומבטל עיכובים הקשורים לתדירות ה-polling. בנוסף, ניתן לאבטח webhooks עם מפתח סודי, בעוד ש-polling לא ניתן לאבטחה. Webhooks טובים פי 10 מ-polling בזמן תגובה (מתחת ל-100ms לעומת עד 60 שניות).

בעיות שאנו פותרים

• תנאי מרוץ: ללא סינון, webhook תופס את כל האירועים, מה שגורם לבניות מיותרות. אנו מגדירים מסננים לפי sys.contentType.sys.id ונושאים כדי להגיב רק לערכים רלוונטיים. לדוגמה, כשפוסט בבלוג מתפרסם, רק העמוד הספציפי הזה מתעדכן, לא כל האתר, מה שמפחית בניות ב-90%.
• אבטחה: endpoint ציבורי פגיע. אנו מוסיפים אימות חתימה דרך כותרת סודית ואם צריך, רשימת IP מורשית. אינטגרציית הסודות של webhooks ב-Contentful מספקת הגנה של 99.9%.
• שרשראות מורכבות: כששינוי בשדה משפיע על מספר עמודים (למשל, כותרת גלובלית), יש צורך בפסילה המונית. אנו משתמשים ב-revalidateTag או בפריסה מלאה בהתאם למשקל השינוי, וחוסכים 80% מדקות הבנייה.
• ניפוי שגיאות: ללא יומן קריאות, קשה להבין למה webhook לא הופעל. אנו מגדירים ניטור והתראות שגיאה, ומפחיתים את ה-MTTR ב-50%.

איך לסנן Webhooks לפי סוג תוכן?

סינון לפי sys.contentType.sys.id הוא נוהג סטנדרטי. בגוף ה-webhook, אנו מוסיפים תנאי שמעביר רק אירועים עבור המודל הרצוי. זה מפחית קריאות handler פי 5–10. בנוסף, ניתן לסנן לפי נושאים: למשל, רק פרסום (Entry.publish), לא ארכוב, מה שמקצץ קריאות לא רלוונטיות ב-70%.

איך ליצור Webhook ב-Contentful ב-5 שלבים

1. עברו ל-Settings → Webhooks בלוח הבקרה של Contentful.
2. לחצו על Add Webhook והזינו את כתובת ה-handler שלכם (למשל, https://mysite.com/api/revalidate).
3. בחרו נושאים: Entry.publish, Entry.unpublish, Asset.publish — בהתאם לתרחיש.
4. הוסיפו מסננים לפי סוג תוכן (sys.contentType.sys.id) כדי לצמצם אירועים.
5. הפעילו כותרת סודית (x-webhook-secret) לאבטחה — זה מגן מפני קריאות לא מורשות.

לאחר מכן, הטמיעו את ה-handler על השרת. להלן דוגמה להגדרת webhook של Next.js ISR.

יצירת Webhook דרך Contentful CMA

const space = await cmaClient.getSpace(spaceId);
await space.createWebhook({
  name: 'Next.js ISR Revalidation',
  url: 'https://mysite.com/api/revalidate',
  topics: ['Entry.publish', 'Entry.unpublish', 'Asset.publish'],
  filters: [
    {
      equals: [{ doc: 'sys.contentType.sys.id' }, 'blogPost'],
    },
  ],
  headers: [
    {
      key: 'x-webhook-secret',
      value: process.env.CONTENTFUL_WEBHOOK_SECRET,
      secret: true,
    },
  ],
  active: true,
});

Handler ב-Next.js (דוגמת webhook של Next.js ISR)

// app/api/revalidate/route.ts
export async function POST(request: Request) {
  const secret = request.headers.get('x-webhook-secret');
  if (secret !== process.env.CONTENTFUL_WEBHOOK_SECRET) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }
  const payload = await request.json();
  const contentTypeId = payload.sys?.contentType?.sys?.id;
  const slug = payload.fields?.slug?.['en-US'];
  const topic = request.headers.get('x-contentful-topic');
  switch (contentTypeId) {
    case 'blogPost':
      if (slug) revalidatePath(`/blog/${slug}`);
      revalidatePath('/blog');
      break;
    case 'landingPage':
      revalidatePath('/');
      break;
    default:
      revalidateTag('contentful');
  }
  return Response.json({ revalidated: true, topic });
}