[examples] Add on-demand revalidation to Contentful example (#39475)

## Feature

- [x] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [x] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have helpful link attached, see `contributing.md`

## Changes

Added in on-demand revalidation for Contentful example. Specifically, added the revalidate api path, a new environment variable which will contain the secret, and some additions to the README.


Co-authored-by: JJ Kasper <22380829+ijjk@users.noreply.github.com>

examples/cms-contentful/.env.local.example

@@ -1,4 +1,5 @@
 CONTENTFUL_SPACE_ID=
 CONTENTFUL_ACCESS_TOKEN=
 CONTENTFUL_PREVIEW_ACCESS_TOKEN=
-CONTENTFUL_PREVIEW_SECRET=
+CONTENTFUL_PREVIEW_SECRET=
+CONTENTFUL_REVALIDATE_SECRET=

examples/cms-contentful/README.md

@@ -183,6 +183,7 @@ Then set each variable on `.env.local`:
 - `CONTENTFUL_ACCESS_TOKEN` should be the **[Content Delivery API](https://www.contentful.com/developers/docs/references/content-delivery-api/) - access token** field of your API key
 - `CONTENTFUL_PREVIEW_ACCESS_TOKEN` should be the **[Content Preview API](https://www.contentful.com/developers/docs/references/content-preview-api/) - access token** field of your API key
 - `CONTENTFUL_PREVIEW_SECRET` should be any value you want. It must be URL friendly as the dashboard will send it as a query parameter to enable preview mode
+- - `CONTENTFUL_REVALIDATE_SECRET` should be any value you want. This will be the value you pass in as a secret header from the Contentful Webhook settings to use **[On-Demand Revalidation](https://vercel.com/docs/concepts/next.js/incremental-static-regeneration#on-demand-revalidation)**
 
 Your `.env.local` file should look like this:
 
@@ -191,6 +192,7 @@ CONTENTFUL_SPACE_ID=...
 CONTENTFUL_ACCESS_TOKEN=...
 CONTENTFUL_PREVIEW_ACCESS_TOKEN=...
 CONTENTFUL_PREVIEW_SECRET=...
+CONTENTFUL_REVALIDATE_SECRET=...
 ```
 
 ### Step 6. Run Next.js in development mode
@@ -247,4 +249,39 @@ Alternatively, you can deploy using our template by clicking on the Deploy butto
 
 This will deploy the Next.js project as well as connect it to your Contentful space using the Vercel Contentful Integration. If you are using Preview Mode, make sure to add `CONTENTFUL_PREVIEW_SECRET` as an [Environment Variable](https://vercel.com/docs/environment-variables) as well.
 
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fcms-contentful&project-name=nextjs-contentful-blog&repository-name=nextjs-contentful-blog&demo-title=Next.js+Blog&demo-description=Static+blog+with+multiple+authors+using+Preview+Mode&demo-url=https%3A%2F%2Fnext-blog-contentful.vercel.app%2F&demo-image=https%3A%2F%2Fassets.vercel.com%2Fimage%2Fupload%2Fv1625705016%2Ffront%2Fexamples%2FCleanShot_2021-07-07_at_19.43.15_2x.png&integration-ids=oac_aZtAZpDfT1lX3zrnWy7KT9VA&env=CONTENTFUL_PREVIEW_SECRET&envDescription=Any%20URL%20friendly%20value%20to%20secure%20Preview%20Mode)
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fcms-contentful&project-name=nextjs-contentful-blog&repository-name=nextjs-contentful-blog&demo-title=Next.js+Blog&demo-description=Static+blog+with+multiple+authors+using+Preview+Mode&demo-url=https%3A%2F%2Fnext-blog-contentful.vercel.app%2F&demo-image=https%3A%2F%2Fassets.vercel.com%2Fimage%2Fupload%2Fv1625705016%2Ffront%2Fexamples%2FCleanShot_2021-07-07_at_19.43.15_2x.png&integration-ids=oac_aZtAZpDfT1lX3zrnWy7KT9VA&env=CONTENTFUL_PREVIEW_SECRET,CONTENTFUL_REVALIDATE_SECRET&envDescription=Any%20URL%20friendly%20value%20to%20secure%20Your%20App)
+
+### Step 9. Try using On-Demand Revalidation
+
+In your Contentful space, go to **Settings > Webhooks** and add a new webhook:
+
+- **Give the webhook a name**
+- **Activate:** Check the activate checkbox to ensure the webhook is marked as active
+- **Specify the POST URL:** Using the URL from your Vercel deployment in step 8, add the path `/api/revalidate` at the end, so it would look something like:
+
+  ```
+  https://<YOUR_VERCEL_DEPLOYMENT_URL>/api/revalidate
+  ```
+
+  Replace `<YOUR_VERCEL_DEPLOYMENT_URL>` with your own deployment URL as noted in the Vercel dashboard.
+
+- **Specify Triggers:** You can choose to trigger for all events or specific events only, such as the Publishing and Unpublishing of Entries and Assets, as shown below.
+
+  ![Content webhook url](./docs/content-webhook-url.png)
+
+- **Specify Secret Header:** Add a secret header named `x-vercel-reval-key` and enter the value of the
+  `CONTENTFUL_REVALIDATE_SECRET` from before.
+
+  ![Content secret header](./docs/content-secret-header.png)
+
+- **Set Content type:** Set content type to `application/json` in the dropdown.
+
+  ![Content publish changes](./docs/content-content-type.png)
+
+- **Edit post:** Now, try editing the title of one of your blog posts in Contentful and click Publish. You should see the changed reflected in the website you just deployed, all without triggering a build! Behind the scenes a call was made to the revalidate api that triggers a revalidation of both the landing page and the specific post that was changed.
+
+  ![Content publish changes](./docs/content-publish-changes.png)
+
+- **Verify:** You can verify if your request was made successfully by checking the webhook request log on Contentful and checking for a successful 200 status code, or by having your functions tab open on Vercel when committing the change (log drains may also be used). If you are experiencing issues with the api call, ensure you have correctly entered in the value for environment variable `CONTENTFUL_REVALIDATE_SECRET` within your Vercel deployment.
+
+  ![Content successful request](./docs/content-successful-request.png)

examples/cms-contentful/pages/api/revalidate.js

@@ -0,0 +1,29 @@
+// pages/api/revalidate.js
+
+export default async function handler(req, res) {
+  // should be secret, custom header coming in from Contentful
+  let inboundRevalToken = req.headers['x-vercel-reval-key']
+
+  // Check for secret to confirm this is a valid request
+  if (!inboundRevalToken) {
+    return res
+      .status(401)
+      .json({ message: 'x-vercel-reval-key header not defined' })
+  } else if (inboundRevalToken !== process.env.CONTENTFUL_REVALIDATE_SECRET) {
+    return res.status(401).json({ message: 'Invalid token' })
+  }
+
+  try {
+    let postSlug = req.body.fields.slug['en-US']
+
+    // revalidate the individual post and the home page
+    await res.revalidate(`/posts/${postSlug}`)
+    await res.revalidate('/')
+
+    return res.json({ revalidated: true })
+  } catch (err) {
+    // If there was an error, Next.js will continue
+    // to show the last successfully generated page
+    return res.status(500).send('Error revalidating')
+  }
+}