Trigger functions on events

For the complete documentation index, see llms.txt

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 get started with functions doc. To subscribe to one or more events, export a default object from your function and add a method for each event you want to handle.

import type { DeploySucceededEvent, DeployFailedEvent } from "@netlify/functions"

export default {
  deploySucceeded(event: DeploySucceededEvent) {
    console.log(`Deploy ${event.deploy.id} succeeded for ${event.site.name}`)
  },

  deployFailed(event: DeployFailedEvent) {
    console.log(`Deploy ${event.deploy.id} failed: ${event.deploy.errorMessage}`)
  },
}

A single function can subscribe to multiple events by declaring the corresponding handlers, and multiple functions can declare a handler for the same event — both will run.

The arguments and return values of all event handlers are fully typed, making them easier to work with by humans and their IDEs, as well as by AI coding agents.

Legacy filename convention

Before the handler syntax above, functions subscribed to events by matching the file name to the event name.

This convention is still fully supported and continues to work for all the events listed below, but new functions should prefer the typed handler syntax — it’s clearer to read, supports multiple events from a single function, and gives you full type checking on the event payload.

For example, the following file would run on every successful deploy:

export default async (req: Request) => {
  const { payload } = await req.json()

  console.log(`Deploy ${payload.id} shipped`)
}

Available event handlers

Deploy events

Handler	Triggered when
`deployBuilding`	Netlify starts building a site for deployment.
`deploySucceeded`	Netlify finishes deploying a site.
`deployFailed`	A deploy does not complete.
`deployDeleted`	A deploy is deleted.
`deployLocked`	A deploy is locked in production and Netlify stops autopublishing deploys.
`deployUnlocked`	A deploy is unlocked from production and Netlify resumes autopublishing deploys.

Each handler receives an event with deploy and site properties.

Identity events

Handler	Triggered when
`userValidate`	A user attempts to sign up, before the account is created. Can reject the signup with `event.deny()`.
`userSignup`	A user completes signup. Can mutate the user record.
`userLogin`	A user logs in. Can reject or mutate.
`userModified`	A user’s profile is updated. Can reject or mutate.
`userDeleted`	A user is deleted. Notification only.

For full details and code examples, see Identity event functions.

Form events

Handler	Triggered when
`formSubmitted`	A form submission is verified for your site.

The handler receives an event with the submission data.

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.

Did you find this doc useful?

Your feedback helps us improve our docs.