Налаштування 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 години.