# Event Hooks > Hooks allow running code when during the Directus lifecycle or database events. Hooks allow running code when events occur within Directus. Events are triggered on schedules, database events, schedules, or during the Directus application lifecycle. ## Hook Entrypoint The `index.js` or `index.ts` file exports a function that is read by Directus. It contains one or more event listeners. ### Entrypoint Example ```js export default ({ filter, action }) => { filter("items.create", () => { console.log("Creating Item!"); }); action("items.create", () => { console.log("Item created!"); }); }; ``` ## Register Function The register function receives an object containing the type-specific register functions as the first parameter:
Type Description
filter Happens before the event is emitted. Use to check, modify, or prevent the event from being emitted.
action Happens after the event is emitted. Use to execute further logic, enrichment, or automations.
init Happens at a defined point within the lifecycle of Directus.
schedule Happens on a defined time interval.
embed Inject custom JavaScript or CSS in the Data Studio.
The second parameter is a context object with the following properties:
Property Description
services All internal Directus services.
database Knex instance that is connected to the current database
getSchema Async function that reads the full available schema for use in services
env Parsed environment variables.
logger Pino instance
emitter Event emitter instance that can be used to emit custom events for other extensions
## Filter Filter events are called before an event is emitted. ```js export default ({ filter }) => { filter("items.create", (payload, meta, context) => { console.log("About to create item."); return payload; }); }; ``` The `filter` register function takes an event name and a callback function that receives the modifiable `payload`, an event-specific `meta` object, and a `context` object when the event is emitted. The `meta` object contains the following properties:
Property Description
event The type of event that is being emitted.
collection The collection where the event is occuring.
The context object has the following properties:
Property Description
database The current database transaction.
schema The current API schema in use.
accountability Information about the current user.
### Filter Events
Name Payload Meta
websocket.authenticate The default accountability object. message
websocket.message The message sent over the WebSocket. client
request.not_found false request , response
request.error The request errors.
database.error The database error. client
auth.login The login payload. status , user , provider , error
auth.jwt The auth token. status , user , provider , type
auth.create 1 The created user. identifier , provider , providerPayload
auth.update 2 The updated auth token 3 . identifier , provider , providerPayload
authenticate The default accountability object. req
email.send The email payload.
(.)items.query The items query. collection
(.)items.read The read item. query , collection
(.)items.create The new item. collection
(.)items.update The updated item. keys , collection
(.)items.promote The promoted item. collection , item , version
(.)items.delete The keys of the item. collection
.query The items query. collection
.read The read item. query , collection
.create The new item. collection
.update The updated item. keys , collection
.delete The keys of the item. collection
1 Available for the `ldap`, `oauth2`, `openid` and `saml` driver. 2 Available for the `ldap`, `oauth2`, and `openid` driver. 3 Available for the `oauth2`, and `openid` driver if set by provider. **Filters are Blocking** Filters can impact performance if not implemented carefully, especially on `read` events, which can lead to many database reads. ## Action Action events are called after an event is emitted. ```js export default ({ action }) => { action("items.create", (meta, context) => { console.log("Item was just created."); }); }; ``` The `action` register function takes an event name and a callback function that receives a `meta` object (containing information about the action and the payload) and a `context` object. The `meta` object contains the following properties:
Property Description
event The type of event that was emitted.
payload The data associated with the event.
key The primary key of the item.
collection The collection where the event occurred.
The context object has the following properties:
Property Description
database The current database transaction.
schema The current API schema in use.
accountability Information about the current user.
### Action Events
Name Meta
websocket.message message , client
websocket.error client , event
websocket.close client , event
websocket.connect client
websocket.auth.success client
websocket.auth.failure client
server.start server
server.stop server
response request , response , ip , duration , finished
auth.login payload , status , user , provider
files.upload payload , key , collection
extensions.load extensions
extensions.unload extensions
extensions.reload extensions , added , removed
extensions.installed extensions , versionId
extensions.uninstalled extensions , folder
(.)items.read payload , query , collection
(.)items.create payload , key , collection
(.)items.update payload , keys , collection
(.)items.promote payload , collection , item , version
(.)items.delete keys , collection
(.)items.sort collection , item , to
.read payload , query , collection
.create payload , key , collection
.update payload , keys , collection
.delete keys , collection
Learn how to build custom WebSocket handlers with practical examples using these hooks. ## Init Init events are called during the Directus application lifecycle. ```js export default ({ init }) => { init("routes.before", (meta) => { console.log(meta); }); }; ``` The `init` register function takes an event name and a callback function that receives `meta`. `meta` contains either `program` or `app` (the full underlying Express application) depending on the lifecycle event. ### Init Events
Name Meta
cli.before program
cli.after program
app.before app
app.after app
routes.before app
routes.after app
routes.custom.before app
routes.custom.after app
middlewares.before app
middlewares.after app
## Schedule Schedule events are called on a defined time interval. ```js export default ({ schedule }) => { schedule("*/15 * * * *", () => { console.log("15 minutes have passed."); }); }; ``` The `schedule` event takes a cron string as the first argument and a callback function as the second argument. The cron string follows the following format: ```text * * * * * * ┬ ┬ ┬ ┬ ┬ ┬ │ │ │ │ │ │ │ │ │ │ │ └ day of week (0 - 7) (0 or 7 is Sun) │ │ │ │ └───── month (1 - 12) │ │ │ └────────── day of month (1 - 31) │ │ └─────────────── hour (0 - 23) │ └──────────────────── minute (0 - 59) └───────────────────────── second (0 - 59, OPTIONAL) ``` ## Embed The embed hook injects custom JavaScript or CSS into the `` and `` tags within the Data Studio. ```js export default ({ embed }) => { embed("body", ''); }; ``` The embed register function requires two parameters - the position of the embed (either `head` or `body`), and a value to embed (either a string or a function that returns a string). ## Sandboxed Hooks When using the sandbox, you have access to `filter` and `action` events only. Callback functions receive the `payload` object as the only parameter. ### TypeScript You can import the `SandboxHookRegisterContext` type from `directus:api` to type the register function's `context` object: ```ts /// import type { SandboxHookRegisterContext } from "directus:api"; export default ({ filter, action }: SandboxHookRegisterContext) => {}; ``` Learn more about the Directus sandbox for API extensions.