Netlify Docs
Ask Netlify

Contact

Platform primitives /Functions /

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

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

# Limitations

  • Password-protected sites. Functions triggered by events won’t work if you have full Site Protection enabled as Netlify doesn’t have access to site credentials or authentication information at event completion. Consider using basic authentication instead for only the sections of the site you need to protect and exclude the functions. Netlify automatically adds a layer of security for your event functions with JSON web signatures.

← Functions & Identity →