Rebuild your static site automatically with Contentful webhoooks

Once you've setup a static site that pulls in your content during the build process, you're ready to configure webhooks that will be triggered when you publish or unpublish content in your space. This tutorial will teach you how to setup webhooks to trigger builds and deployments of static sites for two providers: Netlify and Heroku.

Netlify

Setting up a Contentful webhook that will trigger a build and deployment of a Netlify site takes only a few steps.

Prerequisites

Your site must already be deployed to Netlify, and you must have configured it for continuous deployment by connecting it to a remote Git repo. If you haven't done so already, follow the guide on the Netlify documentation.

Configuring a Netlify build hook

From the Netlify dashboard, navigate to the "Settings" for your site, choose "Build & deploy", and scroll to "Build hooks".

Netlify dashboard

Click "Add build hook", give your webhook a memorable name, and choose the branch you'd like to build. Netlify will generate an HTTPS URL which will respond to POST requests by triggering a build and deployment of your site. Copy the URL and navigate back to the Contentful web app. Navigate to "Space settings", then "Webhooks" by clicking from the top navigation bar. Click "Add webhook", and paste the URL that Netlify provided into the URL form, and give your webhook a name.

Contentful webhook

You can choose to filter which events in Contentful should trigger Netlify builds. For this example, we'll only trigger builds when entries and assets have been published or unpublished.

Save the webhook and you're done! Now when you publish a content change, your Netlify site will be built and deployed.

Heroku

If you are hosting your static site with Heroku, you'll need an intermediate system to automate the build. For this section of the tutorial, we'll use CircleCI to build and deploy our site to Heroku.

Prerequisites

You must have an account with CircleCI and your site must already be deployed to Heroku. You should also have a remote Git repo configured for your project hosted on either Github, GitLab, or Bitbucket. For our purposes, we'll assume the project is hosted on Github.

Building on CircleCI

First, navigate to the CircleCI dashboard, select the correct Github organization from the dropdown in the top left, click "ADD PROJECTS", and select your Git repo. Click "Start building" to finish connecting your Git repo (you can ignore the initial build itself).

Setup circle project

In order for your repo to run a build on CircleCI, you'll need the relevant configuration files. Create a directory called .circleci in your project root directory, with one file called config.yml inside it. Copy the code below to .circleci/config.yml. It is a basic CircleCI configuration to build a NodeJS project that checks out the latest commit of the current branch, installs npm dependencies, builds, and finally then deploys the site. Note that this config file will deploy all branches to the production server, so the deploy script should be changed to fit your setup before it can be used in production. Refer to the CircleCI documentation for further reference on finding a continuous integration pipeline that suits your needs.

version: 2
jobs:
  build:
    docker: # run the steps with Docker
      - image: circleci/node:8
    steps:
      - checkout
      - run:
          name: update npm
          command: 'sudo npm install -g npm@latest'
      - restore_cache:
          key: dependency-cache-{{ checksum "package.json" }}
      - run:
          name: Install node modules
          command: npm install 
      - run: 
          name: Build
          command: npm run build
      - run:
          name: Deploy
          command: git push https://heroku:$HEROKU_API_KEY@git.heroku.com/$HEROKU_APP_NAME.git
      - save_cache:
          key: dependency-cache-{{ checksum "package.json" }}
          paths:
            - ./node_modules

Commit this file to your branch, and push it to Github. You should see a job begin to execute in the CircleCI dashboard, and all the steps should pass in the build job. The deploy job should fail as we have not yet added the relevant environment variables for Heroku. Navigate to your Heroku account to grab your token for the Heroku Platform API, copy it.

Heroku API key

Navigate back to the settings for your CircleCI project and click "Environment Variables". Add an environment variable with a name HEROKU_API_KEY. For the value, paste the key you copied from Heroku. Copy your Heroku project name and paste it as the value for an environment variable called HEROKU_APP_NAME. If you have other environment variables necessary for your project to build, add them now.

Circle environment variables

Triggering a CircleCI build with a webhook

The last variable we'll need to grab is your CircleCI Personal Access Token. You can create this token in the "User Settings" in CircleCI. After you've copied your new token to your clipboard, navigate back to the Contentful web app, go to "Space settings" > "Webhooks" by clicking from the top navigation bar. Click "Add webhook", and paste in the following URL:

https://circleci.com/api/v1.1/project/github/<GITHUB_ORG>/<GITHUB_PROJECT>/tree/master?circle-token=<YOUR_CIRCLE_TOKEN>

Contentful heroku webhook

Note: Visit the CircleCI API documentation for information about the URL structure if you're using other Git providers, or if you'd like to build for other branches.

You can choose to filter which events in Contentful should trigger CircleCI builds. For this example, we'll only trigger builds when entries and assets have been published or unpublished.

Save the webhook and you're done! Now when you publish a content change, a CircleCI job will be triggered which builds and deploys your Heroku site.