Deploy Hooks allow you to create URLs that accept HTTP POST requests in order to trigger deployments and re-run the Build Step. These URLs are uniquely linked to your project, repository, and branch, so there is no need to use any authentication mechanism or provide any payload to the POST request.

This feature allows you to integrate ZEIT Now deployments with other systems. For example, you can set up:

  • Automatic deployments by hooking into content changes in Headless CMSs.
  • Scheduled deployments by configuring third-party cron job services to trigger the Deploy Hook.
  • Forced deployments from the command line.

Creating a Deploy Hook

To create a Deploy Hook for your project, make sure your project is linked to a Git repository using our Git Integrations.

Importing a project using our Git Integrations.

Once your project is connected, navigate to its "Settings" page and then select the Git Integration menu item.

Selecting the Git Integration menu item from the Project Settings page.

In the "Deploy Hooks" section, choose a name for your Deploy Hook and select the branch that will be deployed when the generated URL is requested.

Creating a new Deploy Hook.

Note: We suggest you use a name that easily identifies the Deploy Hook so you will be able to understand when it triggers a deployment. We also suggest creating only one Deploy Hook per branch unless you’re using multiple data sources.

After submitting the form, you will see a URL that you can copy and use.

Triggering a Deploy Hook

To trigger a Deploy Hook, send a POST request to the provided URL. Here's an example request and response you can use for testing:

Example Request

curl -X POST https://api.zeit.co/v1/integrations/deploy/QmcwKGEbAyFtfybXBxvuSjFT54dc5dRLmAYNB5jxxXsbeZ/hUg65Lj4CV

Example Response

{
  "job": {
    "id": "A7OcAEEgNRh61p1VZXE1",
    "state": "PENDING",
    "createdAt": 1564399503217
  }
}

Information for a successful Deploy Hook job.

Note: You do not need to add any authorization header or use any token as the URL already identifies your linked project.

After sending a POST request, you can see that it triggered a deployment on your project dashboard.

Technical Details

  • Triggering a Deploy Hook will not rebuild an existing deployment. Instead, it will create a new deployment using the latest source code available on the specified branch.
  • Currently, no build cache is used when triggering a Deploy Hook.
  • If you send multiple requests to deploy the same version of your project, previous deployments for the same Deploy Hook will be canceled to reduce build times.