Code-based nature means you can build on top of it to power anything.
Resources
DocumentationExamplesTemplatesGitHubBlog
Community
RoadmapDiscordCommunity Help
Payload Cloud

Deploy your entire stack in one place with Payload Cloud.

LoginCloud Pricing
It’s time to take back your content infrastructure.
Schedule a Demo
Enterprise Features
SSOPublishing WorkflowsVisual EditorStatic A/B testingAI features
Customer Stories
MicrosoftBlue OriginHello BelloMythical SocietyTekton
Featured Customer Story

Microsoft chose Payload to tell the world about AI.

Read the case study
New projectLogin
New projectLogin

Global Hooks

Global Hooks are Hooks that run on Global Documents. They allow you to execute your own logic during specific events of the Document lifecycle.

To add Hooks to a Global, use the hooks property in your Global Config:

1
import type { GlobalConfig } from 'payload';
2
3
export const GlobalWithHooks: GlobalConfig = {
4
// ...
5
hooks: {
6
// ...
7
},
8
}

Config Options

All Global Hooks accept an array of synchronous or asynchronous functions. Each Global Hook receives specific arguments based on its own type, and has the ability to modify specific outputs.

1
import type { GlobalConfig } from 'payload';
2
3
const GlobalWithHooks: GlobalConfig = {
4
// ...
5
hooks: {
6
beforeValidate: [(args) => {...}],
7
beforeChange: [(args) => {...}],
8
beforeRead: [(args) => {...}],
9
afterChange: [(args) => {...}],
10
afterRead: [(args) => {...}],
11
}
12
}

beforeValidate

Runs before the update operation. This hook allows you to add or format data before the incoming data is validated.

1
import type { GlobalBeforeValidateHook } from 'payload'
2
3
const beforeValidateHook: GlobalBeforeValidateHook = async ({
4
data,
5
req,
6
originalDoc,
7
}) => {
8
return data
9
}

The following arguments are provided to the beforeValidate hook:

OptionDescription
globalThe Global in which this Hook is running against.
contextCustom context passed between Hooks. More details.
dataThe incoming data passed through the operation.
originalDocThe Document before changes are applied.
reqThe Web Request object. This is mocked for Local API operations.

beforeChange

Immediately following validation, beforeChange hooks will run within the update operation. At this stage, you can be confident that the data that will be saved to the document is valid in accordance to your field validations. You can optionally modify the shape of data to be saved.

1
import type { GlobalBeforeChangeHook } from 'payload'
2
3
const beforeChangeHook: GlobalBeforeChangeHook = async ({
4
data,
5
req,
6
originalDoc,
7
}) => {
8
return data
9
}

The following arguments are provided to the beforeChange hook:

OptionDescription
globalThe Global in which this Hook is running against.
contextCustom context passed between hooks. More details.
dataThe incoming data passed through the operation.
originalDocThe Document before changes are applied.
reqThe Web Request object. This is mocked for Local API operations.

afterChange

After a global is updated, the afterChange hook runs. Use this hook to purge caches of your applications, sync site data to CRMs, and more.

1
import type { GlobalAfterChangeHook } from 'payload'
2
3
const afterChangeHook: GlobalAfterChangeHook = async ({
4
doc,
5
previousDoc,
6
req,
7
}) => {
8
return data
9
}

The following arguments are provided to the afterChange hook:

OptionDescription
globalThe Global in which this Hook is running against.
contextCustom context passed between hooks. More details.
docThe resulting Document after changes are applied.
previousDocThe Document before changes were applied.
reqThe Web Request object. This is mocked for Local API operations.

beforeRead

Runs before findOne global operation is transformed for output by afterRead. This hook fires before hidden fields are removed and before localized fields are flattened into the requested locale. Using this Hook will provide you with all locales and all hidden fields via the doc argument.

1
import type { GlobalBeforeReadHook } from 'payload'
2
3
const beforeReadHook: GlobalBeforeReadHook = async ({
4
doc,
5
req,
6
}) => {...}

The following arguments are provided to the beforeRead hook:

OptionDescription
globalThe Global in which this Hook is running against.
contextCustom context passed between hooks. More details.
docThe resulting Document after changes are applied.
reqThe Web Request object. This is mocked for Local API operations.

afterRead

Runs as the last step before a global is returned. Flattens locales, hides protected fields, and removes fields that users do not have access to.

1
import type { GlobalAfterReadHook } from 'payload'
2
3
const afterReadHook: GlobalAfterReadHook = async ({
4
doc,
5
req,
6
findMany,
7
}) => {...}

The following arguments are provided to the beforeRead hook:

OptionDescription
globalThe Global in which this Hook is running against.
contextCustom context passed between hooks. More details.
findManyBoolean to denote if this hook is running against finding one, or finding many (useful in versions).
docThe resulting Document after changes are applied.
queryThe Query of the request.
reqThe Web Request object. This is mocked for Local API operations.

TypeScript

Payload exports a type for each Global hook which can be accessed as follows:

1
import type {
2
GlobalBeforeValidateHook,
3
GlobalBeforeChangeHook,
4
GlobalAfterChangeHook,
5
GlobalBeforeReadHook,
6
GlobalAfterReadHook,
7
} from 'payload'
Next

Field Hooks

On this page
Star on GitHub

Star

Chat on Discord

Discord

online