Contentful Webhook Integrations Setup

Setting up Contentful Webhook Integrations

Webhooks in Contentful trigger on content changes: publishing, archiving, entry creation, asset deletion. Primary use — cache invalidation and static site rebuilds without polling.

Creating a Webhook

In Web App: Settings → Webhooks → Add Webhook. Via 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: [
    // Only for specific Content Type
    {
      equals: [{ doc: 'sys.contentType.sys.id' }, 'blogPost'],
    },
  ],
  headers: [
    {
      key: 'x-webhook-secret',
      value: process.env.CONTENTFUL_WEBHOOK_SECRET,
      secret: true, // value hidden in UI
    },
  ],
  active: true,
});

Webhook Handler in 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 });
}

Integration with Vercel Deploy Hooks

For static regeneration of entire site — direct call to Vercel Deploy Hook:

// Separate webhook endpoint for full rebuild
export async function POST(request: Request) {
  await fetch(process.env.VERCEL_DEPLOY_HOOK_URL!, { method: 'POST' });
  return Response.json({ triggered: true });
}

Filtering by topics allows separation: small edits → ISR-invalidation of specific page, structural changes → full deploy.

Transformations and Retry

Contentful retries webhook requests on errors (non-2xx status) with exponential backoff. View call history — Settings → Webhooks → [webhook name] → Activity. For debugging use webhook.site as temporary URL during development.

Basic webhook setup (ISR + Netlify/Vercel build trigger) takes 2–4 hours.