Trigger functions on events

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

Async Workloads Extension

Event-triggered serverless functions support built-in event triggers using serverless functions. If you’re looking to build durable, event-based architecture, refer to the Async Workloads documentation for more information.

An event-triggered function is built like any other, as described in the get started with functions doc. 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.ts or deploy-succeeded.go.
• to trigger a background function on deploy-succeeded events, name the function file something like deploy-succeeded-background.ts or deploy-succeeded-background.go.

When the event occurs, Netlify will automatically run the function you’ve created for that trigger. For example, when Netlify finishes deploying a site and triggers the deploy-succeeded event, the function declared in deploy-succeeded.ts will execute.

Available triggers

Deploy triggers

• 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-deleted: Triggered when a deploy is deleted.
• 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.

Identity triggers

For details and code examples, refer to Identity event functions.

• identity-validate: Triggered when a user attempts to sign up. This event can be used to selectively block or approve signups.
• identity-signup: Triggered after a new user has signed up. For email-based signups, this event is triggered after the user has confirmed their email address. This event cannot be used to block a signup.
• identity-login: Triggered when a user logs in.

Form triggers

• submission-created: Triggered when a form submission is verified for your site.

Split test triggers

• 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.

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.