Trigger functions on events

You can trigger serverless function calls when certain Netlify events happen, like when a deploy completes successfully.

An event-triggered function is built like any other, as described in the build with JavaScript, TypeScript, and Go docs. To make it trigger on an event, match the name of the function file to the name of the event. For example,

  • to trigger a synchronous function on deploy-succeeded events, name the function file something like deploy-succeeded.js or deploy-succeeded.go.
  • to trigger a background function on deploy-succeeded events, name the function file something like deploy-succeeded-background.js or deploy-succeeded-background.go.

# Available triggers

The following events are currently available:

  • deploy-building: Triggered when Netlify starts building a site for deployment.
  • deploy-succeeded: Triggered when Netlify finishes deploying a site.
  • deploy-failed: Triggered when a deploy does not complete.
  • deploy-locked: Triggered when a deploy is locked in production and Netlify stops autopublishing deploys.
  • deploy-unlocked: Triggered when a deploy is unlocked from production and Netlify resumes autopublishing deploys.
  • split-test-activated: Triggered when a split test is activated.
  • split-test-deactivated: Triggered when a split test is deactivated.
  • split-test-modified: Triggered when a split test’s settings change.
  • submission-created: Triggered when a form submission is verified for your site.
  • identity-validate: Triggered when an Identity user tries to sign up using Identity.
  • identity-signup: Triggered when an Identity user signs up using Netlify Identity and confirms their email address. Note that this fires for email+password signups only, not for signups with external providers such as Google or GitHub.
  • identity-login: Triggered when an Identity user logs in using Netlify Identity.

# Payload

The request body for these functions is a JSON document that includes information about the associated site, as well as the object that triggered the event, such as a deploy, split test, or verified form submission. All payloads have this shape:

{
  "payload": {
    # information about the object that triggered the event
  },
  "site": {
    # information about the associated site
  }
}

# Signature

To prevent external requests to event functions, Netlify generates a JSON web signature (JWS) for each event triggered by our platform, and verifies that the signature is correct before invoking an associated event function.