Настройка 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 }); }