How to Use Webhooks in a Headless CMS Content Architecture

Your content editor publishes an updated pricing page. Your Next.js site is statically generated and deployed on Vercel. Without webhooks, the live site still shows the old prices until someone manually triggers a rebuild. With webhooks, the publish event fires a request to Vercel's revalidation endpoint, the pricing page rerenders, and the CDN cache clears — all within 30 seconds of the editor clicking Publish.

What ContentGrid Sends in a Webhook

ContentGrid's webhook payload includes the event type (entry.publish, entry.unpublish, entry.delete, asset.upload), the entry ID, the content type, the locale, and the environment. That's enough information to route the event intelligently in your handler — you don't have to query the CMS to figure out what changed.

Payload example fields: eventType, entryId, contentType, locale, environment, changedFields. The changedFields array tells your handler exactly which fields were updated, so you can make smarter invalidation decisions.

Common Webhook Targets

• Vercel revalidation API: Call /api/revalidate?path=/blog/my-post to rebuild a specific page without a full site deploy.
• Netlify build hook: Trigger a full rebuild when schema or global content (navigation, site settings) changes.
• Algolia index: Push updated content to your search index when entries are published or deleted.
• Slack notification: Post to a #content-updates channel when content is published, so the team knows what went live.
• CRM or analytics: Log content publish events for attribution and experiment tracking.

Building a Reliable Webhook Handler

Your webhook handler is an API route — a Next.js edge function or a serverless function on Vercel or Netlify. It receives the POST request from ContentGrid, validates the signature (ContentGrid signs every payload with a secret), processes the event, and responds with a 200 status quickly. Do not run slow operations synchronously in the handler. Put heavy work — rebuilding an Algolia index, sending batch notifications — on a queue and process it asynchronously.

Validate the webhook signature on every request. ContentGrid includes an X-ContentGrid-Signature header with an HMAC-SHA256 hash of the payload. Reject requests that don't match your secret. This prevents bad actors from triggering rebuilds or index updates by hitting your handler URL directly.

Testing Webhooks in Development

Use a tunneling tool like ngrok to expose your local Next.js dev server to ContentGrid's webhook delivery. Register the ngrok URL as a webhook endpoint in your ContentGrid space settings, then publish an entry. You'll see the full payload in your terminal and can iterate on your handler logic before deploying to production.