Webhooks

Netlify supports both incoming and outgoing webhooks.

Incoming webhooks notify our servers to do something. Outgoing webhooks request another service to do something when events happen with your sites.

Incoming webhooks

The only supported action for incoming webhooks right now is to trigger new builds and deploys. These webhooks are often referred to as build hooks. You can find them in your site dashboard at Settings > Build & deploy > Continuous deployment > Build hooks.

null

Select Add build hook to create a new build hook. The build hook name is for your reference, and will display in your list of build hooks, as well as in the default deploy message for each deploy triggered by the hook.

Select a branch to build by default. Only branches which have been deployed at least once will appear in this list.

Upon saving your build hook settings, Netlify will give you a unique URL for that webhook. To trigger this hook, you need to send a POST request to that URL.

In most cases, this POST request will be sent from a service you want to integrate with Netlify, but you can also send these requests yourself. For example, you can run a cURL command from your terminal:

curl -X POST -d '{}' https://api.netlify.com/build_hooks/XXXXXXXXXXXXXXX

You can also test webhook requests with tools like API Tester or Postman.

Build hook metadata

Build hook accept the following optional URL query parameters to alter the behavior of the triggered build:

  • trigger_branch: Specify which repository branch the build will use. If the branch does not exist in your repository at the time of the build, the build will fail, with an error message in the build log.
  • trigger_title: Specify a title to replace the default deploy message in your site deploy list.

Here is an example build hook URL using both available parameters:

https://api.netlify.com/build_hooks/XXXXXXXXXXXXXXX?trigger_branch=testing&trigger_title=triggered+by+This+Awesome+Service

This would trigger a deploy from an existing branch called testing, with a custom message: triggered by This Awesome Service.

Deploy list item for a branch deploy from the 'testing' branch, with message, 'triggered by This Awesome Service'

Build hook payload

You can send a custom payload in your build hook POST request. The contents must be passed as a string, which will be URL-encoded and made available in the triggered build as an environment variable. You can access it in the build by using the variable INCOMING_HOOK_BODY.

Outgoing webhooks and notifications

Outgoing webhooks are useful to notify other services when something happens with your site in Netlify.

This is the list of current events supported by Netlify:

  • Deploy started: this event is emitted when Netlify starts building your site for a new deploy.
  • Deploy succeeded: this event is emitted when Netlify finishes propagating a new deploy in our CDN.
  • Deploy failed: this event is emitted when a deploy does not complete.
  • Deploy locked: this event is emitted when a deploy is locking a site.
  • Deploy unlocked: this event is emitted when a deploy stops locking a site.
  • New form submission: this event is emitted when a form submission is verified for your site.

You can enable notifications for deploy events in your site dashboard at Settings > Build & deploy > Deploy notifications. Select the type of notification you want to create and add the required configuration.

null

Notifications for form submissions can be configured in your site dashboard at Settings > Forms > Form notifications.

URL notifications

This feature may not be available on all plans.

This webhook 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

Signing URL notification payloads

If you provide a JWS secret token for URL notifications, 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 webhook allows you to send event information to an email address of your choice.

null

Slack notifications

This feature may not be available on all plans.

This webhook 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

GitHub commit statuses

This webhook 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/or retry the deploy.

null

These notifications are added to all new GitHub-connected Netlify sites by default. You can add, remove, or edit them from the site dashboard at 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 webhook 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 from the site dashboard at Settings > Build & deploy > Deploy notifications.

null

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

GitHub pull request comments

This webhook 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 webhook will update the comment to indicate status changes.

null

You can add a GitHub pull request comment notification from the site dashboard at 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

GitLab commit statuses

This webhook creates commit statuses in your GitLab repositories.

null

It requires a GitLab API token with access to the repository. You can set that token when you configure this notification:

null

GitLab merge request comments

This webhook 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 webhook will update the comment to indicate status changes.

null

It requires a GitLab API token with access to the repository. You can set that token when you configure this notification:

null

Bitbucket notifications

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

Zapier integration

This feature may not be available on all plans.

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 start a new deploy of your site in response to a trigger from another service. You can find out more on our blog, or use one of the templates below to get started:


Notice something is incorrect or outdated?

First off, great catch! We appreciate your discovery and want to ensure it gets addressed immediately. Please let us know here.



Want to have a conversation?

Visit the Netlify Community to discuss ideas and questions with your fellow Netlify users.

Want to get started quick?