Настройка Webhook-интеграций Contentful

Настройка Webhook-интеграций Contentful

Webhooks в Contentful срабатывают при изменении контента: публикация, архивация, создание записи, удаление ассета. Основное применение — инвалидация кэша и ребилд статических сайтов без polling.

Создание Webhook

В Web App: Settings → Webhooks → Add 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: [
    // Только для конкретного Content Type
    {
      equals: [{ doc: 'sys.contentType.sys.id' }, 'blogPost'],
    },
  ],
  headers: [
    {
      key: 'x-webhook-secret',
      value: process.env.CONTENTFUL_WEBHOOK_SECRET,
      secret: true, // значение скрыто в UI
    },
  ],
  active: true,
});

Обработчик Webhook в 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'); // e.g. 'ContentManagement.Entry.publish'

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

Интеграция с Vercel Deploy Hooks

Для статической регенерации всего сайта — прямой вызов Vercel Deploy Hook:

// Отдельный webhook endpoint для полного ребилда
export async function POST(request: Request) {
  await fetch(process.env.VERCEL_DEPLOY_HOOK_URL!, { method: 'POST' });
  return Response.json({ triggered: true });
}

Фильтрация по топикам позволяет разделить: мелкие правки → ISR-инвалидация конкретной страницы, структурные изменения → полный деплой.

Трансформации и retry

Contentful повторяет webhook-запросы при ошибках (статус не 2xx) с экспоненциальной задержкой. Просмотр истории вызовов — в Settings → Webhooks → [webhook name] → Activity. Для отладки удобно использовать webhook.site как временный URL при разработке.

Настройка базового набора webhooks (ISR + Netlify/Vercel build trigger) занимает 2–4 часа.