Skip to content

Instant Revalidation

A statically generated site shows content as it was at build time. This example adds a route that Plenary calls through a webhook whenever a post is created, edited, published, unpublished, or deleted. The route checks a shared secret and calls Next.js’s revalidatePath for the pages that show that post, so the next visitor sees the change, usually within seconds of the editor saving.

It builds on the Blog with Next.js example: a post model, a blog index at /blog, and post pages at /blog/{slug}. The same route works for any App Router site; only the path mapping changes.

  • The blog from Blog with Next.js, or another Next.js App Router project (Next.js 14, 15, or 16) that reads Plenary content with @plenary/client.
  • A console account that can manage webhooks on the post model (content:webhooks:manage; the Admin role has it).
  • A URL Plenary can reach. In production that is your deployed site. To test from your machine, a tunnel such as ngrok or cloudflared.
  1. An editor saves or publishes a post.
  2. Plenary queues a delivery and, a moment later, sends POST /api/revalidate to your site with a JSON body describing the event and an x-plenary-secret header.
  3. The route verifies the secret, reads the model key and slug from the body, and calls revalidatePath("/blog") and revalidatePath("/blog/<slug>").
  4. Next.js re-renders those pages on their next request, fetching fresh content from Plenary.

Plenary does not sign webhook requests. The secret header, which you mark Secret in the console so it is never shown again or written to history, is how your route knows the call came from Plenary.

Terminal window
npm install @plenary/next

Keep it on the same version as @plenary/client.

Generate a random value and add it to .env.local (and to your hosting provider’s environment settings):

Terminal window
openssl rand -hex 32
.env.local
PLENARY_BASE_URL=https://your-instance.plenarycms.io
PLENARY_API_KEY=pln_pub_your_public_key
PLENARY_SITE_KEY=default
PLENARY_LOCALE=en-us
PLENARY_WEBHOOK_SECRET=paste-the-generated-value-here
app/api/revalidate/route.ts
import { createRevalidateHandler } from "@plenary/next";
const secret = process.env.PLENARY_WEBHOOK_SECRET;
const handler = createRevalidateHandler({
secret: secret ?? "",
paths: {
// A changed post refreshes the blog index and the post's own page.
post: ({ entry }) => (entry.slug ? ["/blog", `/blog/${entry.slug}`] : ["/blog"]),
},
});
export async function POST(request: Request) {
// Without a configured secret, refuse everything rather than compare against "".
if (!secret) {
return Response.json({ message: "PLENARY_WEBHOOK_SECRET is not set" }, { status: 503 });
}
return handler(request);
}

paths maps a model key to the pages that show its entries. The function receives the webhook payload; entry.slug is the post’s slug, and entry.path is its folder path if you use content folders. A model without a paths item gets a default path built from its folder path and slug (/blog + spring-sale gives /blog/spring-sale), which only fits sites whose routes mirror the folder tree. See @plenary/next for every option.

The if (!secret) guard matters: with an empty secret, a request with ?secret= (empty) would be accepted.

Revalidation applies to cached, prerendered pages, which only exist in a production build. next dev renders every request fresh, so you cannot see revalidation there.

Terminal window
npm run build
npm start

The site is now on http://localhost:3000.

Check the route before connecting Plenary. A wrong secret is refused:

Terminal window
curl -s -X POST http://localhost:3000/api/revalidate \
-H "x-plenary-secret: wrong" \
-d '{}'
{"message":"Invalid webhook secret"}

A request shaped like Plenary’s revalidates the pages and says which:

Terminal window
curl -s -X POST http://localhost:3000/api/revalidate \
-H "x-plenary-secret: $PLENARY_WEBHOOK_SECRET" \
-d '{"event":"entry.updated","delivery_id":"test-1","model":{"id":"test","key":"post"},"entry":{"id":"test","slug":"hello-plenary","path":"/"},"actor":{"type":"user","label":"curl"},"changed":["data.title"]}'
{"revalidated":true,"paths":["/blog","/blog/hello-plenary"],"tags":[]}

Run that in a shell where PLENARY_WEBHOOK_SECRET is exported with the same value as .env.local.

Response Status Meaning
{"revalidated":true,"paths":[…],"tags":[…]} 200 Revalidated.
{"revalidated":false,"ignored":"form.submitted"} 200 A form event, or an event you excluded with events. Nothing to do.
{"message":"Invalid webhook secret"} 401 Header missing or value wrong.
{"message":"Body is not valid JSON"} or {"message":"Not a Plenary webhook payload"} 400 Not a Plenary request.
{"message":"Method not allowed"} 405 Not a POST.
{"message":"PLENARY_WEBHOOK_SECRET is not set"} 503 The environment variable is missing.

Plenary must be able to reach the route. For local testing, open a tunnel to port 3000:

Terminal window
ngrok http 3000

ngrok prints a public https://…ngrok-free.app URL. Your webhook URL is that URL plus /api/revalidate.

Webhook URLs must use HTTPS. A self-hosted instance running with dev_mode: true also accepts plain http URLs, which lets a Plenary instance on your own machine call http://host.docker.internal:3000/api/revalidate directly (from a Docker container) without a tunnel.

  1. Go to Content Management → Content. On the Posts card, open Model actions and choose Edit.

  2. Open the Webhooks tab and choose Add webhook.

  3. Fill in the dialog:

    Setting Value
    Name Next.js revalidation
    URL https://your-site.example.com/api/revalidate (or your ngrok URL plus /api/revalidate)
    Events Entry created, Entry updated, Entry published, Entry unpublished, Entry deleted
    Headers Add header: name x-plenary-secret, value your PLENARY_WEBHOOK_SECRET, and turn on Secret
    Fields No field data (the route needs only the slug, which every payload carries)
    Active On
  4. Close the dialog, then choose Save model. Webhook changes are staged with the rest of the model and are not stored until you save.

Once saved, the secret value is never shown again; the console offers to replace it instead.

To revalidate for every model on a site with one webhook, add it on the site instead: Admin Settings → Site Management, open the site, then its Webhooks tab. Add a paths item to the route for each model your site renders.

  1. Open http://localhost:3000/blog (or your deployed site) and note a post’s title.
  2. In the console, edit that post’s title and choose Save Changes (it stays published).
  3. Wait a few seconds and reload the page. The new title appears.

To see what happened, open the webhook’s Deliveries drawer from its row on the Webhooks tab. Each delivery shows its event, status (Delivered, Failed, Queued, or Sending), response code, attempt count, and the exact payload sent. A successful delivery looks like this:

{
"event": "entry.updated",
"delivery_id": "1f9478ea-9d6a-4d27-9002-b70f76a99eeb",
"occurred_at": "2026-10-07T09:19:28.905Z",
"webhook": { "id": "49307ac4-62e6-4411-86cf-f68340b56638", "name": "Next.js revalidation" },
"model": { "id": "8750e6b3-844b-4786-a47c-ca6d9757bfbc", "key": "post" },
"entry": {
"id": "3f982d3b-6e46-4fda-9602-3eab4e2826dc",
"site_key": "default",
"locale": "en-us",
"slug": "second-post",
"path": "/",
"status": "published",
"created_at": "2026-10-07T09:12:48.388Z",
"updated_at": "2026-10-07T09:19:28.904Z",
"published_at": "2026-10-07T09:12:53.753Z"
},
"actor": { "type": "user", "id": "6063d721-3d78-4f06-b983-0aed7300408b", "label": "editor@example.com" },
"changed": ["data.title"],
"revision_id": "77665ce5-3465-4458-9d27-0fa05d112f25"
}
Editor action Event Effect with this route
Creates a post entry.created Revalidates /blog and the new slug. A draft is not shown to a public key, so the pages render as before.
Edits a post entry.updated Revalidates /blog and the post.
Publishes, by hand or on a schedule entry.published The post appears on /blog, and its page renders.
Unpublishes, by hand or on a schedule entry.unpublished The post leaves /blog; its page returns 404.
Deletes a post entry.deleted Same as unpublishing.
Moves a post to another folder entry.updated Revalidates as an edit. If your URLs include the folder path, revalidate the old path too.

A save that changes nothing fires no event. Creating and publishing in one step (Save and Publish on a new entry) sends both entry.created and entry.published, and they can arrive in either order; revalidating twice is harmless.

If a delivery fails with a 5xx or a timeout, Plenary retries it after 30 seconds, 2 minutes, 10 minutes, 1 hour, and 6 hours. A 4xx answer (such as a wrong secret) fails the delivery at once, so it shows up in the Deliveries drawer instead of retrying for hours.

Path mapping works when you know which URLs show a post. When the same content appears on many pages (a “latest posts” sidebar, a home page, a sitemap), revalidate by cache tag instead: tag every Plenary read with the model and entry it used, and let the webhook revalidate the tags. That needs two changes, both described in @plenary/next:

Symptom Cause and fix
Delivery Failed with 401 The header name or value does not match. The header must be x-plenary-secret and its value must equal PLENARY_WEBHOOK_SECRET exactly. Replace the secret in the webhook dialog and save the model.
Delivery Failed with no response code Plenary could not reach the URL. Check the tunnel is running and the URL ends in /api/revalidate.
Saving the model fails with “Webhook URLs must use HTTPS.” Use an https:// URL, such as the ngrok one.
Delivery Delivered but the page did not change You are running next dev, or the paths in paths do not match your routes. Send the delivery’s payload to the route with curl, as above, and compare the paths in the answer with your URLs.
503 PLENARY_WEBHOOK_SECRET is not set Add the variable to the environment where the site runs, then restart or redeploy.
No delivery appears at all The webhook is paused, not saved (choose Save model), or not subscribed to the event.