Atlas Platform Features: Deployment Previews & Webhooks
Tags: devops, webdev, wordpress, headless
Published: 2022-09-21 15:33:19

In this article, I will discuss the new Preview Environments and Webhook features in the [Atlas](https://wpengine.com/atlas/) platform.  If you are new to Headless WordPress and would like to start testing out Atlas, sign up for a free sandbox account [here](https://wpengine.com/atlas/#atlasplans)!

## The Modern Developer Workflow

Modern web developers using a git-based approach to development expect certain features and functionality on their hosting platforms, especially ones that support their CI/CD (Continuous Integration and Continuous Delivery) workflows.  

In the past, hosting platforms only allowed you to deploy sites to the same URL every time you pushed a change.  If you wanted to test changes before making them live on your production site, you had to manually create new sites or environments with new URLs to preview those changes. 

For example, in some workflows, you may have testing or staging branches tied to specific environments, and committing to those branches could help you automatically preview your changes before merging them into production. While you can still do this with Atlas environments, this Git flow strategy may be too rigid for some teams or conflict with other philosophies on repository management.

Luckily, the Atlas platform has a solution for this issue that makes CI/CD less tedious and more flexible to implement. 

## Deployment Previews

<!-- wp:paragraph -->
<p>The Atlas team got me super stoked as we now have <a href="https://developers.wpengine.com/docs/atlas/additional-guides/preview-environments">deployment previews!!</a> This allows you and your team to see changes on your site without having to deploy them to your production site and without having to create a dedicated testing branch or environment.  </p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>The value for the modern developer's workflow is a less tedious, quicker way to enable better productivity.  As a developer, this helps you achieve constant collaboration and iteration for a quicker "ship more and ship fast flow."</p>
<!-- /wp:paragraph -->

## How Deployment Previews Work

Deployment previews work by deploying every pull request from your GitHub repository to a specific preview environment, with its own URL, logging, and tools, in relation to the feature branch you created.  This isolates each branch you make from your main production branch without having to manually spin up entirely new site environments!

You and your team can view the unique URL to see how these changes look before they are merged into production and deployed.

In order to enhance the workflow even more you can access information about the Atlas preview environment in two places:  the GitHub UI and the Atlas Platform UI:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1nplbtxk1363xedh4d1o.png)



![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zfis8u6i95eqjg7hw0zw.png)


You can link back and forth between UI's conveniently as well.

As you iterate and develop your site, you can continuously push multiple changes, checkout multiple branches, and share these URLs for collaboration and feedback, in turn exponentially increasing overall developer and team productivity.  Under the hood, Atlas keeps up with your feature branch changes, builds the environment, and provides the unique URL! ⚡

Please visit the preview environment [docs](https://developers.wpengine.com/docs/atlas/additional-guides/preview-environments) for a step-by-step guide on usage.


## Deployment Previews FAQs


#### I Don't See Deployment Previews Anywhere in the Atlas Platform 

The deployment previews feature needs to be enabled on a per-environment basis, which means if you want to preview PRs submitted against your main or production branch, [the setting needs to be enabled for that Atlas environment. ](developers.wpengine.com/docs/atlas/additional-guides/preview-environments#enable-the--preview-environments--feature(opens in a new tab))


#### Do Deployment Previews Count Towards My Resources?

No, any deployment previews that you create do not count towards your plan entitlements. 

#### What Happens if I Make Additional Commits to a PR?

If you continue to make commits to a feature branch with an open PR, Atlas will detect those changes and rebuild your deployment preview.

#### How Do I Delete a Deployment Preview?

The main mechanism for managing preview environments is the PR lifecycle. If you close a PR or merge it into its target branch, those actions will automatically delete the deployment preview associated with the PR. 


## Atlas Environment Rebuild Webhooks


The modern git-based workflow gets me JAMstoked because it enables quick continuous streamlined workflows with all things expected to be connected once things are spun up and pushed into your repository.


Often times though, there are teams of content creators or other technical/non-technical stakeholders who are not immersed in the git-based flow but still need a way to push changes from the WordPress CMS to the front-end of their headless site. For example, if a site is using SSG, a content editor may want to rebuild a particular post or page whenever they update the resource in WordPress.


### What is a Webhook?

This is where webhooks come into the workflow.  A webhook is an HTTP-based callback function that allows lightweight, event-driven communication between two APIs. 

In this case, the WP Engine Atlas platform features webhooks that allow users to trigger an environment rebuild from an event created by WordPress. (e.g. updating, deleting, adding posts)


## Configuring Builds with Atlas Webhooks 

The Atlas platform makes it really easy to generate a webhook to rebuild your environment via WordPress events.  

**Step 1:** Go into your Atlas account and on to the Atlas accounts home page.  Click on any app environment you choose:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/amon9fdgb6b1lpd8wss1.png)


**Step 2:**  Once you choose an app environment and click on it, you will be taken to an environment settings page.  Click on the `Settings` link:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ha1glvjtzme94i8rcg8e.png)


Step 3:  Clicking on the Settings link takes you to the Settings page.  In the lower half of the page, you will see a Environment `webhook` pane.  Click the Create a `webhook` button:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/g84h24jznu6p1uue46et.png)


Once you click that, an endpoint will be generated like this:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/35f730h2m68710xu8uc3.png)


Copy that endpoint URL because we are going to need it for our WordPress backend.


### Embed the Webhook in WordPress

Now that your webhook is created on the Atlas platform, go into your WP Admin.  From here, you can select a plugin that will help trigger your Atlas webhook based on an action you do in WordPress, such as adding a new post for example.  

You can use any plugin you like and we have some other suggestions in our docs, but in this example, I will use WP Webhooks.  

Go to the side menu of your WP Admin and hit `Plugins > Add` `New` and search for WP Webhooks.  It should be the first one you see:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8ooqf0x8prjk6sxqlyel.png)




Once you install and activate the plugin, it will give you an option on the menu under Settings.  Click on WP Webhooks there:



![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ipwkjg506mfd6x7obc3w.png)



Atlas Platform Features: Deployment Previews & Webhooks
In this article, I will discuss the new Preview Environments and Webhook features in the Atlas platform.  If you are new to Headless WordPress and would like to start testing out Atlas, sign up for a free sandbox account here!

The Modern Developer Workflow
Modern web developers using a git-based approach to development expect certain features and functionality on their hosting platforms, especially ones that support their CI/CD (Continuous Integration and Continuous Delivery) workflows.  

In the past, hosting platforms only allowed you to deploy sites to the same URL every time you pushed a change.  If you wanted to test changes before making them live on your production site, you had to manually create new sites or environments with new URLs to preview those changes. 

For example, in some workflows, you may have testing or staging branches tied to specific environments, and committing to those branches could help you automatically preview your changes before merging them into production. While you can still do this with Atlas environments, this Git flow strategy may be too rigid for some teams or conflict with other philosophies on repository management.

Luckily, the Atlas platform has a solution for this issue that makes CI/CD less tedious and more flexible to implement. 

Deployment Previews
The Atlas team got me super stoked as we now have deployment previews!! This allows you and your team to see changes on your site without having to deploy them to your production site and without having to create a dedicated testing branch or environment.  

The value for the modern developer's workflow is a less tedious, quicker way to enable better productivity.  As a developer, this helps you achieve constant collaboration and iteration for a quicker "ship more and ship fast flow."

How Deployment Previews Work
Deployment previews work by deploying every pull request from your GitHub repository to a specific preview environment, with its own URL, logging, and tools, in relation to the feature branch you created.  This isolates each branch you make from your main production branch without having to manually spin up entirely new site environments!

You and your team can view the unique URL to see how these changes look before they are merged into production and deployed.

In order to enhance the workflow even more you can access information about the Atlas preview environment in two places:  the GitHub UI and the Atlas Platform UI:

This image has an empty alt attribute; its file name is Screen-Shot-2022-09-07-at-4.42.17-PM-1024x575.png
This image has an empty alt attribute; its file name is Screen-Shot-2022-09-07-at-4.45.12-PM-1024x452.png
You can link back and forth between UI's conveniently as well.  

As you iterate and develop your site, you can continuously push multiple changes, checkout multiple branches, and share these URLs for collaboration and feedback, in turn exponentially increasing overall developer and team productivity.  Under the hood, Atlas keeps up with your feature branch changes, builds the environment, and provides the unique URL! ⚡

Please visit the preview environment docs for a step-by-step guide on usage.

Deployment Previews FAQs
I Don't See Deployment Previews Anywhere in the Atlas Platform
The deployment previews feature needs to be enabled on a per-environment basis, which means if you want to preview PRs submitted against your main or production branch, the setting needs to be enabled for that Atlas environment. 

Do Deployment Previews Count Towards My Resources?
No, any deployment previews that you create do not count towards your plan entitlements. 

What Happens if I Make Additional Commits to a PR?
If you continue to make commits to a feature branch with an open PR, Atlas will detect those changes and rebuild your deployment preview.

How Do I Delete a Deployment Preview?
The main mechanism for managing preview environments is the PR lifecycle. If you close a PR or merge it into its target branch, those actions will automatically delete the deployment preview associated with the PR. 

Atlas Environment Rebuild Webhooks
The modern git-based workflow gets me JAMstoked because it enables quick continuous streamlined workflows with all things expected to be connected once things are spun up and pushed into your repository.

Often times though, there are teams of content creators or other technical/non-technical stakeholders who are not immersed in the git-based flow but still need a way to push changes from the WordPress CMS to the front-end of their headless site. For example, if a site is using SSG, a content editor may want to rebuild a particular post or page whenever they update the resource in WordPress.

What is a Webhook?
This is where webhooks come into the workflow.  A webhook is an HTTP-based callback function that allows lightweight, event-driven communication between two APIs. 

In this case, the WP Engine Atlas platform features webhooks that allow users to trigger an environment rebuild from an event created by WordPress. (e.g. updating, deleting, adding posts)

Configuring Builds with Atlas Webhooks 
The Atlas platform makes it really easy to generate a webhook to rebuild your environment via WordPress events.  

Step 1: Go into your Atlas account and on to the Atlas accounts home page.  Click on any app environment you choose:

This image has an empty alt attribute; its file name is Screen-Shot-2022-09-17-at-12.17.07-PM-1024x448.png
Step 2:  Once you choose an app environment and click on it, you will be taken to an environment settings page.  Click on the Settings link:

This image has an empty alt attribute; its file name is Screen-Shot-2022-09-20-at-10.21.01-AM-1024x580.png
Step 3:  Clicking on the Settings link takes you to the Settings page.  In the lower half of the page, you will see an Environment webhook pane.  Click the Create a webhook button:

This image has an empty alt attribute; its file name is Screen-Shot-2022-09-17-at-12.25.30-PM-1024x519.png
Once you click that, an endpoint will be generated like this:

This image has an empty alt attribute; its file name is Screen-Shot-2022-09-17-at-12.29.54-PM-1024x519.png
Copy that endpoint URL because we are going to need it for our WordPress backend.

Embed the Webhook in WordPress
Now that your webhook is created on the Atlas platform, go into your WP Admin.  From here, you can select a plugin that will help trigger your Atlas webhook based on an action you do in WordPress, such as adding a new post for example.  

You can use any plugin you like and we have some other suggestions in our docs, but in this example, I will use WP Webhooks.  

Go to the side menu of your WP Admin and hit Plugins > Add New and search for WP Webhooks.  It should be the first one you see:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/q9l8qtcgdcxl2nogpvii.png)


Once you install and activate the plugin, it will give you an option on the menu under Settings.  Click on WP Webhooks there:



![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qqpq6828mwlzf1kz0hbi.png)



This will bring you to the WP Webhooks main page.  In this case, we want to send data via a POST request to the Atlas platform when the webhook is triggered, so click on the Send Data option at the top: 


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/frs48ojz1525jq6mq7vv.png)


Next, you will have options on what actions you want to associate with your webhook trigger.  Let's use Post updated.  Once you choose the action, click on Add Webhook URL:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/q5sin6r30xt9jyaeyon4.png)


When you select those options, you will see a modal pop-up that will ask you to name your webhook and embed the webhook you created from Atlas:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hjqxyzgvlnstqumphnbd.png)


And done!!! The next thing to do is go and create a new post.  When you hit publish on that post, you can go to your Atlas account in WP Engine and see that a build was triggered due to the action in your WordPress backend!! Stoked! 🎉


This feature here allows the modern web teams the ability to update data without having to touch code or jump into a command line.

Please reference the [docs](https://developers.wpengine.com/docs/atlas/customization/builds#rebuild-an-environment-via-webhook) as well for webhooks.  


## Stay Tuned, more Atlas features to come...

These two features are table stakes that modern jamstack/decoupled hosting platforms should have.  The addition of these features to the Atlas platform will improve your modern web dev workflow across all your teams and stakeholders.

Stay tuned for more Atlas features to come!  As always let us know your feedback, thoughts, and ideas in [Discord](https://discord.com/invite/J2khkF9XYK)!