Deploy notifications

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

Netlify supports the following deploy events:

• 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 deleted: event emitted when a deploy is manually deleted.
• 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.
• Deploy restored: event emitted when a deploy is manually published (usually for rollback or rollforward.
• Previously successful deploy failed: event emitted when a deploy was previously successful but then failed.
• Previously failed deploy succeeded: event emitted when a deploy succeeded after it had failed.

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

You can also set up Slack notifications with our Netlify App for Slack.

Slack notifications

Send deploy event information to a Slack channel. Learn more in our Netlify App for Slack docs.

Email notifications

This feature is available on all Pro and Enterprise plans.

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

HTTP Post Request

This type of notification works as an outgoing webhook and 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.

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

If your project uses Node.js with Express for backend, you need to compare the incoming request data before it’s transformed to JSON:

import crypto from "crypto";
import jwt from "jsonwebtoken";
import express from "express";

const app = express();

// parse body and keep the raw contents
app.use(
  bodyParser.json({
    verify: (req, res