Налаштування webhook-інтеграцій Contentful: ISR, кеш, деплой

Чому push-сповіщення стали стандартом для Contentful

Уявіть: ви публікуєте запис у блозі через Contentful, а на сайті він з'являється лише через 15 хвилин — тому що білд запускається раз на годину. Або після правки хедера перезбираються всі сторінки, хоча змінилася одна панель. Це типові сценарії, коли без webhook не обійтися. Webhooks вирішують проблему миттєво: зміни контенту (публікація, архівація, видалення) ініціюють виклик вашого обробника. Це основа безшовної роботи для SSR/ISR-сайтів. Один webhook може заощадити до 90% на API-трафіку за рахунок безполінгового оновлення. Ми налаштовуємо webhook-інтеграції під ключ — від простого ребілду статики до точкової інвалідації сторінок.

Переваги webhook перед polling

Polling Contentful API кожні N секунд — зайве навантаження та затримка. Webhook, навпаки, не потребує постійних запитів: сервер сам повідомляє вас про зміни. Це знижує навантаження на API в 10 разів та виключає затримки, пов'язані з частотою опитування. Крім того, webhook можна захистити секретним ключем, а polling — ні.

Проблеми, які вирішуємо

• Гонка запитів: без фільтрації webhook ловить всі події, викликаючи зайві ребілди. Ми налаштовуємо фільтри за sys.contentType.sys.id та топіками, щоб реагувати тільки на потрібні записи. Наприклад, при публікації статті оновлюється тільки конкретна сторінка, а не весь сайт.
• Безпека: публічний endpoint вразливий. Додаємо перевірку підпису через секретний заголовок і, при необхідності, IP-білий список.
• Складний ланцюжок: при зміні поля, яке впливає на кілька сторінок (наприклад, глобальний хедер), потрібна масова інвалідація. Використовуємо revalidateTag або повний деплой — залежно від ваги зміни.
• Налагодження: без журналу викликів складно зрозуміти, чому webhook не спрацював. Налаштовуємо моніторинг та сповіщення про помилки.

Як фільтрувати webhook за типом контенту?

Фільтрація за sys.contentType.sys.id — стандартний прийом. У тілі webhook ми додаємо умову, яка пропускає події тільки для потрібної моделі. Це скорочує кількість викликів обробника в 5–10 разів. Додатково можна фільтрувати за топіками: наприклад, тільки публікація (Entry.publish), без архівації.

Як створити webhook у Contentful за 5 кроків?

1. Перейдіть у Settings → Webhooks у панелі керування Contentful.
2. Натисніть Add Webhook та вкажіть URL вашого обробника (наприклад, https://mysite.com/api/revalidate).
3. Виберіть топіки: Entry.publish, Entry.unpublish, Asset.publish — залежно від сценарію.
4. Додайте фільтри за типом контенту (sys.contentType.sys.id) для звуження подій.
5. Увімкніть секретний заголовок (x-webhook-secret) для безпеки — це захистить від несанкціонованих викликів.

Після цього залишається реалізувати обробник на сервері. Нижче — приклад для Next.js.

Створення webhook через 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, }); 

Обробник у Next.js

// 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 }); }