Setup Content Publisher Invalidation On Static Sites
This document details the set-up instructions for Pantheon Content Publisher when using a static site. This ensures that the latest content from your document is available for preview and publishing to your static site.
Static site pages are built ahead of time so they can be delivered to your users as quickly as possible. This poses a challenge when these pages have to be updated after they have been created and published to your site. Updating your content without updating the static page shown to users results in your users getting stale content.
Content Publisher lets your static site know when a published article has been updated using a webhook notification. This unlocks powerful use cases for your static site like updating the content displayed on a page after publishing or making a page private after publishing it to the internet publicly.
- Terminal with Node.js installed (https://nodejs.org/en/download)
To get started with Content Publisher webhook updates, setup webhook delivery by providing the URL you want to receive the webhooks at to Content Publisher.
The below listed commands should be ran in a terminal of your choice.
Download the Content Publisher CLI from NPM.
npm install @pantheon-systems/pcc --global
Login to the CLI
pcc login
You will be taken to a browser page to login to your account, after which you should return to the terminal.
List out the sites you have available for configuration
pcc site list
A list of your Content Publisher sites will be displayed. Copy the ID of the site you want to configure webhooks for
The Content Publisher Site Configure command allows you to configure the “Webhook URL” as well as the “Webhook Secret” for your Content Publisher Site.
- Webhook URL
This refers to the URL at which your application listens for webhook events sent by Content Publisher.
- Webhook Secret
This refers to a value attached to the webhook events sent you could use to verify the events, ensuring they are actually coming from Content Publisher.
Configure the Webhook URL by providing the –webhook-url argument to the configure site command
pcc site configure <site-id> --webhook-url <url-of-webhook-listener>
Configured with values, this would look like:
pcc site configure abcde1122 --webhook-url https://example.com/webhook
Run the command and you should get confirmation your site has been updated with the provided webhook url.
Configure the Webhook Secret by providing the –webhook-secret argument to the configure site command
pcc site configure <site-id> --webhook-secret <webhook-secret-value>
Configured with values, this would look like:
pcc site configure abcde1122 --webhook-secret very-secret-key
Run the command and you should get confirmation your site has been updated with the provided webhook secret.
You could also configure both the webhook url and secret at the same time by providing the `--webhook-url` and `--webhook-secret` arguments at the same time to `pcc site configure`.
The webhook sent to your URL will be an HTTP POST request with a body containing identifying information about the article that was updated as well as what kind of update was applied to the article.
You can expect the webhook request sent to have a body with the following properties:
- event: string (Identifies the type of event)
- payload
- articleId: string (The ID of the article that was updated)
The following events are currently supported:
- 'article.update' (Article content or metadata has been updated)
- 'article.publish' (Article has been marked as published)
- 'article.unpublish' (Article has been marked as unpublished)
If you set a Webhook Secret it will be sent as part of the request headers under the “x-pcc-webhook-secret” key.
Example webhook request:
Now that you have configured Content Publisher to send webhooks to your URL of choice, we have to configure handlers on our site to receive the webhooks and modify the updated page.
If you use a frontend site hosting service like Pantheon, Vercel and Netlify among others, this is easy to set up as these services come with support for rebuilding sites when webhooks come in. This guide will go through configuring webhooks with some of these services as well as on self-hosted setups.
You can trigger rebuilds of your site hosted on Pantheon Frontend Sites automatically by taking advantage of Pantheon Frontend Site Build Hooks and Pantheon Content Publisher Webhooks.
Follow the Build Hooks documentation to add a Build Hook. Copy the Build Hook URL provided to you and provide it to Content Publisher as discussed in Getting Started to complete your Build Hooks setup.
Content Publisher will now automatically trigger rebuilds of your site deployed on Pantheon when the content in your article changes.
You can listen for webhooks sent from Content Publisher to handle rebuilding pages using Next.js’s On Demand Revalidation feature.
This involves setting up an API route handler to listen for webhook events then call the revalidate function to trigger page rebuilds.
The official Next.js documentation goes into detail about setting up this handler in this article.
All you have to do is provide the URL of your handler to Content Publisher after setting it up to get on demand revalidation working.
For a more generalized approach to invalidation of static pages, you could trigger rebuilds for any site deployed to Vercel using Vercel’s deploy hooks feature.
The Vercel documentation page contains up to date instructions on how to create a deploy hook. After creating the deploy hook a URL will be provided to you. Add that URL to Content Publisher like following the steps described above in Getting Started to use your deploy hook.
Now, on subsequent updates to articles in your site, your deployed Vercel site will be rebuilt.
Vercel opts you in by default into Build Step caching so your rebuilds are fast (only changed content is rebuilt) however if you would like to opt out of this append `?buildCache=false` to the URL you provide to Content Publisher.
For sites deployed to Netflify, you could take advantage of Netlify Build Hooks to trigger rebuilds of site pages when your Content Publisher article is updated.
The Build Hooks documentation page contains up to date instructions on how to setup a Build Hook for triggering builds. Upon saving the build hook settings, Netlify will give you a unique URL for that build hook.
Provide that URL to Content Publisher following the steps outlined in Getting Started and subsequent updates to your articles on Content Publisher will cause your site deployed on Netlify to be rebuilt.
The core principle behind webhook invalidation can be applied to any static framework, regardless of specific implementation details. That is, you get notified of an update to an article and you rebuild your site.
The granularity of the rebuild is left up to you but for scalability rebuilding only the page that changes is recommended.
Whatever your setup is, you essentially need to set up a handler that receives the webhook and triggers the rebuild and subsequent update of the page that has changed.