Setting up Contentful Webhook Integrations: ISR, Cache, Deployment

Why Push Notifications Became the Standard for Contentful

Imagine: you publish a blog post via Contentful, but it appears on the site only 15 minutes later — because the build runs once an hour. Or after editing the header, all pages are rebuilt even though only one panel changed. These are typical scenarios where webhooks are indispensable. Webhooks solve the problem instantly: content changes (publish, archive, delete) trigger your handler. This is the foundation of seamless operation for SSR/ISR sites. A single webhook can save up to 90% on API traffic by eliminating polling, and reduce API costs by up to $500/month. We configure webhook integrations turnkey — from simple static rebuilds to targeted page invalidation. Our Contentful webhook setup experience spans over 50 successful integrations, each with a $200–$1500 setup cost and typical savings of $500/month.

Benefits of Webhooks over Polling

Polling the Contentful API every 10 seconds creates extra load and latency. Webhooks, in contrast, require no constant requests: the server itself notifies you of changes. This reduces API load by 10x and eliminates delays tied to polling frequency. Additionally, webhooks can be secured with a secret key, while polling cannot. Webhooks are 10 times better than polling for response time (under 100ms vs. up to 60 seconds).

Problems We Solve

• Race conditions: Without filtering, a webhook catches all events, causing unnecessary rebuilds. We configure filters by sys.contentType.sys.id and topics to react only to relevant entries. For example, when a blog post is published, only that specific page is updated, not the entire site, reducing rebuilds by 90%.
• Security: A public endpoint is vulnerable. We add signature verification via a secret header and, if needed, an IP whitelist. Our Contentful webhook secrets integration provides 99.9% protection.
• Complex chains: When a field change affects multiple pages (e.g., a global header), mass invalidation is needed. We use revalidateTag or a full deploy depending on the change's weight, saving 80% of build minutes.
• Debugging: Without a call log, it's hard to figure out why a webhook didn't fire. We set up monitoring and error notifications, reducing MTTR by 50%.

How to Filter Webhooks by Content Type?

Filtering by sys.contentType.sys.id is a standard practice. In the webhook body, we add a condition that only passes events for the desired model. This reduces handler calls by 5–10x. Additionally, you can filter by topics: for example, only publication (Entry.publish), not archiving, cutting irrelevant calls by 70%.

How to Create a Webhook in Contentful in 5 Steps

1. Go to Settings → Webhooks in the Contentful dashboard.
2. Click Add Webhook and enter your handler URL (e.g., https://mysite.com/api/revalidate).
3. Select topics: Entry.publish, Entry.unpublish, Asset.publish — depending on the scenario.
4. Add filters by content type (sys.contentType.sys.id) to narrow events.
5. Enable a secret header (x-webhook-secret) for security — this protects against unauthorized calls.

After that, implement the handler on the server. Below is an example for a Next.js ISR webhook configuration.

Creating a Webhook via Contentful 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, }); 

Handler in Next.js (Next.js ISR webhook example)

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