Deploy notifications

Deploy notifications can inform you or external services about your site’s deploy activity.

This is the list of deploy events supported by Netlify:

  • Deploy started: event emitted when Netlify starts building your site for a new deploy.
  • Deploy succeeded: event emitted when Netlify finishes uploading a new deploy to our CDN.
  • Deploy failed: event emitted when a deploy does not complete.
  • Deploy locked: event emitted when the site is locked to a published deploy, stopping auto publishing.
  • Deploy unlocked: event emitted when deploys are unlocked, resuming auto publishing.
  • Deploy request pending: event emitted when an untrusted deploy requires approval to begin building.
  • Deploy request accepted: event emitted when an untrusted deploy request is accepted and can begin building.
  • Deploy request rejected: event emitted when an untrusted deploy request is rejected.

You can enable notifications for deploy events in Site settings > Build & deploy > Deploy notifications. Select the type of notification you want to create and add the required configuration.

null

# Slack notifications

This feature may not be available on all plans.

This type of notification allows you to send messages to a Slack channel when Netlify emits events.

Before configuring this notification, make sure you read Slack’s documentation on incoming webhooks.

null

# Outgoing webhooks

This type of notification allows you to send event information to an arbitrary URL using a POST request.

The body of the outgoing webhook request will have a JSON representation of the object relevant to the event.

null

# Payload signature

If you provide a JWS secret token for an outgoing webhook, Netlify will generate a JSON Web Signature(JWS) and send it along with the notification in the request header X-Webhook-Signature.

We include the following fields in the signature’s data section:

  • iss: always sent with value netlify, identifying the source of the request
  • sha256: the hexadecimal representation of the generated payload’s SHA256

You can use any JWT client library to verify this signature in the service receiving the notification. This is an example of an API built with the Sinatra framework that verifies the signature header:

require "digest"
require "jwt"
require "sinatra"

def signed(request, body)
  signature = request["X-Webhook-Signature"]
  return unless signature

  options = {iss: "netlify", verify_iss: true, algorithm: "HS256"}
  decoded = JWT.decode(signature, "your signature secret", true, options)

  ## decoded :
  ## [
  ##   { sha256: "..." }, # this is the data in the token
  ##   { alg: "..." } # this is the header in the token
  ## ]
  decoded.first[:sha256] == Digest::SHA256.hexdigest(body)
rescue JWT::DecodeError
  false
end

post "/netlify-hook" do
  body = request.body.read
  halt 403 unless signed(request, body)

  json = JSON.parse(body)
  # do something with the notification payload here
end

# Email notifications

This feature may not be available on all plans.

This type of notification allows you to send event information to an email address of your choice.

null

# GitHub commit statuses

This type of notification sets commit status directly in your GitHub pull requests and commit lists. For successful deploys, this will include a link to the Deploy Preview. For failed deploys, this will include a link to the detail page for the deploy where you can examine the deploy log and retry the deploy.

null

These notifications are added to all new GitHub-connected Netlify sites by default. You can add, remove, or edit them in Site settings > Build & deploy > Deploy notifications.

The settings include a field for a custom message, which will replace the “Deploy preview ready!” message that displays by default.

null

# GitHub pull request comments

This type of notification adds a comment to your GitHub pull requests indicating the status of the associated deploy and providing a link to the Deploy Preview when ready. If you append more commits to a pull request, this notification will update the comment to indicate status changes.

null

GitHub pull request comment notifications are added to all new GitHub-connected Netlify sites by default. You can add, remove, or edit them in Site settings > Build & deploy > Deploy notifications.

The settings include a field for a custom message, which will replace the “Deploy preview ready!” message that displays by default.

null

# GitHub commit checks

This type of notification adds rich deploy information from your deploy summary to your GitHub pull requests and commit lists. This includes more detailed information in the Checks tab of your pull requests on GitHub.

null

These notifications are added to all new GitHub-connected Netlify sites by default. You can add, remove, or edit them in Site settings > Build & deploy > Deploy notifications.

null

If you don’t find the option for GitHub commit checks in the Add notification menu, you will need to configure your site to use the Netlify GitHub App.

# GitLab commit statuses

Personal access token (PAT) required

If your deploy notifications stop working, you may need to add a GitLab PAT to Netlify. Learn more at our Troubleshoot GitLab notifications docs.

This type of notification creates commit statuses in your GitLab repositories.

null

You can configure this notification through the Netlify UI using your GitLab personal access token (PAT). Your PAT must have the api scope. Learn more in GitLab’s PAT docs. You can add, remove, or edit access in Site settings > Build & deploy > Deploy notifications.

# GitLab merge request comments

Personal access token (PAT) required

If your deploy notifications stop working, you may need to add a GitLab PAT to Netlify. Learn more at our Troubleshoot GitLab notifications docs.

This type of notification adds a comment to your GitLab merge requests indicating the status of the associated deploy and providing a link to the Deploy Preview when ready. If you append more commits to a merge request, this notification will update the comment to indicate status changes.

null

You can configure this notification through the Netlify UI using your GitLab personal access token (PAT). Your PAT must have the api scope. Learn more in GitLab’s PAT docs. You can add, remove, or edit access in Site settings > Build & deploy > Deploy notifications.

# Troubleshoot GitLab deploy notifications

If you set up your GitLab deploy notifications with a GitLab API access token, you’ll need to edit your notifications settings in the Netlify UI and add a GitLab personal access token (PAT).

GitLab 15.0 no longer supports OAuth tokens without an expiration date and introduced a 2-hour expiration window. Learn more about expiring tokens in GitLab’s OAuth docs.

Use Git Gateway or collaborative Deploy Previews?

Your connection to GitLab for these features may also be impacted by the GitLab 15.0 update. Learn more about how to resolve these issues for Git Gateway or collaborative Deploy Previews.

# GitLab deploy notifications stop working

If your GitLab deploy notifications stop working, ensure that you are using a GitLab personal access token (PAT) with the right scopes.

  1. On GitLab, generate a new GitLab PAT with the api scope. Learn more in GitLab’s PAT docs.
  2. On Netlify, add your GitLab PAT for each desired deploy notification at Site settings > Build & deploy > Deploy notifications.

# Bitbucket notifications

Bitbucket deploy notifications are not available because Bitbucket’s API functionality does not support Deploy Previews.

# Azure DevOps notifications

This feature is in BETA. Learn more about Netlify’s Azure DevOps support.

Deploy notifications for Azure DevOps allow your team to check out the latest deploy status and Deploy Preview from Azure DevOps.

# Azure DevOps commit statuses

This type of notification adds a Netlify Deploy Preview link to the Commit details page for successfully deployed commits.

To set up this notification, you must create an Azure DevOps personal access token (PAT) with Code: Read & write permissions.

Once you have a PAT, configure the notification on Netlify. Go to Site settings > Build & deploy > Deploy notifications, select Azure DevOps commit status, and add your PAT.

null

Once configured, you can open a Deploy Preview for a commit with a successful build. To open a Deploy Preview from Azure DevOps, go to the Commit details page, and select the succeeded build status for the desired commit.

null

null

# Azure DevOps pull request comments

This type of notification adds a comment to your Azure DevOps pull requests with a Deploy Preview link and deploy status. This comment automatically updates with any new commits to your pull request.

null

To set up this notification, you must create an Azure DevOps personal access token (PAT) with Code: Read & write permissions.

Once you have a PAT, configure this notification on Netlify. Go to Site settings > Build & deploy > Deploy notifications, select Azure DevOps pull request comment, and add your PAT.

null

# Notifications for monorepos or repositories building multiple apps

For monorepos or setups where one repository builds multiple applications, you can manage the amount of commit status and commit check notifications for sites linked from GitHub or GitLab. This team-level setting works in tandem with deploy notifications configured individually for each site. Check out our monorepo docs to learn more.

# Zapier integrations

Netlify is available on Zapier, where you can connect Netlify with over 1,000 other applications. You can use Zapier “Zaps” to trigger an action in another service on every successful deploy or when a deploy does not complete. You can find out more on our blog, or use one of the templates below to get started:

Receive Slack channel messages on successful Netlify deploys
Netlify + Slack
Use this Zap
Receive Slack notifications for failed production deploys on Netlify
Filter by Zapier + Netlify + Slack
Use this Zap
Show new Netlify deployments in Status Hero
Netlify + Status Hero
Use this Zap
Make ServiceNow records from new Netlify deploy failures
Netlify + ServiceNow
Use this Zap
Plant trees with Ecologi when new deploys in Netlify succeed
Ecologi + Netlify
Use this Zap

# n8n integrations

Netlify is available on n8n, an open source tool that allows you to connect Netlify with other applications. By using one of n8n's Netlify nodes, you can create your own automated workflow. To get started, you can use the Netlify node, Netlify Trigger node, or you can use the existing workflow below:

Send notification when deployment fails
Netlify Trigger Node
Use workflow

Incoming webhooks

Build hook metadata

Build hook payload