How to Automate Deployments on Content Change in WordPress with WP Webhooks and Netlify

WordPress and JavaScript-based frameworks like Next.js and Gatsby make powerful combos, delivering a great CMS editing experience with a fast and performant front end, but if we’re using WordPress headlessly, we don’t automatically have a mechanism to trigger a new deploy. How can we take advantage of web hooks to make sure our websites are always up to date?

What's Inside 🧐

What are WordPress hooks?

Hooks are a fundamental part of how WordPress works. It provides an entry point for developers to listen for actions or events and trigger another process when those occur.

When using WordPress headlessly as a content management system (CMS), we’re primarily interested in listening to events related to content. That could be if a new post is created, update, or even deleted.

By listening to those content-related hooks, we can trigger new deployments wherever our front end is deployed, to make sure any time content is changed, we’re keeping our website fresh with updates.

What are Netlify build hooks?

In this example, we’re using Netlify for where our front end will be deployed.

Netlify, like other providers, provides the ability to create build hooks where when receiving a POST request, will trigger a new build and deployment.

We can do this on really any branch we want, as long as we’ve deployed that branch to Netlify before, but the most common use case is the production branch, commonly main.

How can we use WordPress and Netlify hooks together?

You might see where this is going, but we can take advantage of hooks from both our CMS and from our hosting provider to trigger a new deployment any time our content changes.

Particularly, we’re going to use the free WP Webhooks plugin which will allow us to custom tailor what events we want to use to trigger a new deployment along with the endpoint we want to trigger, which we can create in Netlify.

What are we going to build?

We’re going to start off by spinning up a new WordPress-powered Next.js application and deploying it “as is” to Netlify. The only pre-requisite here is that you already have a basic WordPress instance that’s ready to power your project.

Our goal here isn’t to build the site itself, but learn how to trigger new deployments when content changes, to make sure our project is always kept fresh on production. If you already have a similar project, feel free to skip Step 0.

Once we have our site, we’ll learn how to deploy our website to Netlify, create a new build hook in Netlify, and learn how to trigger that hook automatically using WordPress.

Step 0: Starting a new Next.js project with Next.js WordPress Starter and deploying it to Netlify

We’ll get our project started by spinning up a new Next.js project with my Next.js WordPress Starter.

Note: we won’t go deep into detail for how to get this up and running, but you can follow along with an in-depth tutorial with How to Create a Headless WordPress Blog with Next.js WordPress Starter

In order for this to work, you’ll need to install the WPGraphQL plugin which you can find right inside of the Plugins marketplace in your WordPress instance.

Then in your terminal, run:

yarn create next-app -e https://github.com/colbyfayock/next-wordpress-starter my-wp-app
# or
npx create-next-app -e https://github.com/colbyfayock/next-wordpress-starter my-wp-app

This will go through and clone the starter project and install all of the dependencies.

Note: feel free to change my-wp-app to the directory and project name of your choice!

Once everything is installed, navigate to that new directory:

cd my-wp-app

And before we try to start off the project, create a new file in the root of the project called .env.local with the following:

WORDPRESS_GRAPHQL_ENDPOINT="https://yourhost.com/graphql"

You’ll want to replace http://yourhost.com/graphql with your WordPress instance’s GraphQL endpoint. After installing WPGraphQL, the endpoint is available at /graphql by default.

Now, you can start up the new project by running:

yarn dev
# or
npm run dev

Which will start up a local development server at http://localhost:3000 where you can now access your new Next.js WordPress project!

Next.js WordPress Starter using spacejelly.dev as content
Next.js WordPress site using spacejelly.dev

Step 1: Deploying a WordPress-powered Next.js application to Netlify

Now that we have our project, we need to get it to Netlify before we can learn how to trigger new builds.

This should be relatively painless if you’re familiar with GitHub already and how to create a new repository.

Note: Netlify also has alternative ways to deploy like the Netlify CLI, but using GitHub is a great way to get a lot of other features like automatic deployments when pushing new code and automatic deploy previews for new pull requests.

The first step is connecting your application to a new Git repository. While Netlify supports a variety of Git providers, I’m going to use GitHub here, but feel free to use your favorite if supported.

If you’re not familiar with creating a new repository, GitHub has a great guide, but as soon as you create your repository, GitHub gives you a list of commands you can run to get started. Because Next.js already is initialized with Git, it’s pretty straightforward to get it connected!

New repository on GitHub for my-wp-app
New GitHub repository

But once we’re set up in GitHub, the next step is to connect our repository to Netlify.

If this is your first time using Netlify, now’s the time to sign up for a free account.

Once in Netlify, we want to select New Site from Git.

Netlify New site from Git button
Creating a new Netlify site

On the next page, you’ll be asked to select your Netlify site from your Git provider.

If you’re following along with me, you’ll want to select GitHub, otherwise, select your provider here.

Netlify will use oAuth to connect to your GitHub account, where once connected, it will show you a list of repositories that you’ve given permission to access.

Here we can find our repository and select it.

Searching for my-wp-app in Netlify
Selecting GitHub repository in Netlify

The next page is where we can set up our configuration for our Netlify build.

The cool thing is Netlify will autodetect a lot of this for you, where if you’re using the Next.js Starter from Step 0, we can leave the Build Command as yarn build and our Publish Directory as out.

Note: if these are different for you, make sure to update them! The out directory should be where the project is ultimately exported to.

Build settings in new Netlify deploy
Netlify build settings

Now before you click Deploy, we have one more step.

Click the Show advanced button where we’ll want to add a new environment variable that includes our WORDPRESS_GRAPHQL_ENDPOINT just like we added in Step 0.

WORDPRESS_GRAPHQL_ENDPOINT environment variable in Netlify build
Creating an environment variable for our WordPress GraphQL endpoint

And now you can hit Deploy site!

At this point, Netlify will spin up a new environment and kick off a build, where it will ultimately deploy our new project.

Note: Netlify gives the option to select a custom sub-domain name. Feel free to go into Domain settings while the site is getting deployed to customize yours!

But once it finishes, we should have our new site deployed to Netlify!

Finished deployment on Netlify

And if you click the link and open it, you should now be able to see your new web project!

Next.js WordPress Starter with spacejelly.dev content deployed to Netlify
Website deployed to Netlify

Step 2: Creating a build hook in Netlify to trigger new deployments

By default Netlify will always rebuild and deploy your project whenever you push changes to your main branch. What it doesn’t do, is automatically rebuild and deploy if your content changes.

To automatically kick that off when our content changes, we can take advantage of Netlify build hooks, where Netlify provides a URL that when sent a POST request, will start that process.

Head over in Netlify to Site Settings, Build & deploy, then scroll down to Build hooks.

Build Hooks in Netlify
Finding Build Hooks in Netlify

Then click Add build hook which will give you two options: a name and a branch to build.

While you can put whatever you want for the name, I’m going to go with “WordPress”. For the Branch to build, you’ll want to use whatever branch is your default branch, which if you’re following along with me, should be main. Then click Save.

Creating WordPress build hook in Netlify
Adding a Build Hook in Netlify

Netlify will now give you a unique URL, which will serve as your build hook!

Now let’s test this out.

If you click on that Build Hook, it will open a little panel where you should now see a cURL command.

Finding cURL command to test Netlify build hook
Netlify Build Hook cURL command

Copy that command, open up your terminal, and run it.

If you head back over to your Site Overview or the Deploys section, you’ll now see that you triggered a new deployment of the site with that command!

Step 3: Installing and configuring the WP Webhooks plugin in WordPress

We have one end of the connection ready to go, where we can now programmatically trigger a website deploy. Now we need to set up WordPress to automatically trigger that hook!

To start, head over to WordPress, navigate to Plugins, and click Add New, where we’re going to add the plugin WP Webhooks.

WP Webhooks plugin in WordPress marketplace
Installing WP Webhooks plugin

Once installed and activated, you can find the WP Webhooks link under Settings in the left sidebar navigation.

Once there, we want to navigate to Send Data, as ultimately, we want to send a request to Netlify telling them we want to rebuild our site.

Send Data section in WP Webhooks
Send Data in WP Webhooks

Now if we scroll down on this page, we’ll see a lot of options for different events that we can hook into, in order to trigger an action.

For our use case, we only want to focus on content creation, particularly, we’re going to trigger our webhook any time any event occurs related to Posts.

Note: if your site supports dynamic content based on any of the other hooks, you can repeat these same steps for those events.

Post created hooks in WP Webhooks
Post created hook in WordPress

Starting from the top, select Post created, then click the Add Webhook URL button.

Once you do, you should now see a dialogue that opened up asking for two things: Webhook Name and Webhook URL.

Similar to before, you can name the Webhook anything you want, but I’m going to name mine Netlify.

For the URL, you should use your unique Netlify Build Hook URL from Step 2.

New webhook using Netlify build hook
Adding a new Webhook URL

Then click Add for post_create.

At this point, you should see a success message stating that your hook has been added. You should additionally now see your webhook listed in the UI.

Repeat this same process for Post deleted, Post trashed, and Post updated to make sure we’re triggering a build on any content updates.

Now let’s test this out!

You have a few options for how to test this out. You can:

  • Add a new Post
  • Edit an existing Post
  • Add a new Page
  • Edit an existing Page

Any of these events should now trigger a new deploy in Netlify.

But once you do, you should now see a new deployment kick off.

New build in Netlify triggered by WordPress build hook
New build in Netlify

And once it’s finished, the site should now be updated with your new content!

Test post that was deployed to Netlify after triggered by WP Webhooks
New test post triggered by WP Webhooks and Netlify

Bonus: if you’re just posting a test post and you added the hook for Post delete, if you now remove that post, it should trigger another build and update your site again!