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.
Prerequisites
Section titled “Prerequisites”- 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
postmodel (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.
How it works
Section titled “How it works”- An editor saves or publishes a post.
- Plenary queues a delivery and, a moment later, sends
POST /api/revalidateto your site with a JSON body describing the event and anx-plenary-secretheader. - The route verifies the secret, reads the model key and slug from the body, and calls
revalidatePath("/blog")andrevalidatePath("/blog/<slug>"). - 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.
Install the package
Section titled “Install the package”npm install @plenary/nextKeep it on the same version as @plenary/client.
Add a secret
Section titled “Add a secret”Generate a random value and add it to .env.local (and to your hosting provider’s environment settings):
openssl rand -hex 32PLENARY_BASE_URL=https://your-instance.plenarycms.ioPLENARY_API_KEY=pln_pub_your_public_keyPLENARY_SITE_KEY=defaultPLENARY_LOCALE=en-usPLENARY_WEBHOOK_SECRET=paste-the-generated-value-hereAdd the route
Section titled “Add the route”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.
Run the site in production mode
Section titled “Run the site in production mode”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.
npm run buildnpm startThe site is now on http://localhost:3000.
Test the route with curl
Section titled “Test the route with curl”Check the route before connecting Plenary. A wrong secret is refused:
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:
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. |
Expose your machine to Plenary
Section titled “Expose your machine to Plenary”Plenary must be able to reach the route. For local testing, open a tunnel to port 3000:
ngrok http 3000ngrok 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.
Add the webhook in the console
Section titled “Add the webhook in the console”-
Go to Content Management → Content. On the Posts card, open Model actions and choose Edit.
-
Open the Webhooks tab and choose Add webhook.
-
Fill in the dialog:
Setting Value Name Next.js revalidationURL 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 yourPLENARY_WEBHOOK_SECRET, and turn on SecretFields No field data (the route needs only the slug, which every payload carries) Active On -
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.
Try it
Section titled “Try it”- Open
http://localhost:3000/blog(or your deployed site) and note a post’s title. - In the console, edit that post’s title and choose Save Changes (it stays published).
- 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"}Which events refresh what
Section titled “Which events refresh what”| 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.
Refresh every page that used an entry
Section titled “Refresh every page that used an entry”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:
- Create the client with
createTaggedFetchand a cachedfetch(createTaggedFetch). - Revalidate tags in the route. On Next.js 16, use the custom handler in Next.js 16 and tags.
Troubleshooting
Section titled “Troubleshooting”| 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. |
Related
Section titled “Related”- @plenary/next: every handler option, tags, and the Pages Router version.
- Webhooks: configuring webhooks in the console.
- Webhook events: payloads, headers, retries, and ordering.
- Blog with Next.js: the site this example extends.