---
sidebar_label: Entity hooks
toc_max_heading_level: 3
doc_id: 481d7cfb-0310-4cfa-8ba2-7283ee367230
description: >-
  Entity hooks let you run custom logic before or after entity lifecycle events,
  such as application creation, scope updates, or deployment writes.
keywords:
  - entity hooks
  - lifecycle events
  - automation
  - approvals
  - nullplatform
---

# Entity hooks

Entity hooks let you define custom behavior during the lifecycle of your entities: applications, scopes, and deployments.

When you configure a hook, nullplatform calls your endpoint on specific entity lifecycle events, running either **before** or **after** its own processing. Your system handles the notification and responds with the outcome. For before-hooks, if no response is received, the entity is blocked and will not proceed.

## Entity hooks vs. approvals

While both entity hooks and approvals help control entity lifecycle events, they serve different purposes:

- **Entity hooks** enable automated, programmatic checks before or after an entity operation. They ensure required preconditions, such as infrastructure setup, are met before proceeding.
- **Approvals** enforce governance policies by requiring human verification before certain actions are executed. They allow for decisions based on contextual metadata, such as blocking deployments during restricted periods. See [Approvals](/docs/approvals) for more information.

Using both entity hooks and approvals, organizations can automate workflows while maintaining control over critical processes.

When both are configured on the same event, approvals take precedence:

1. The approval request is sent first, leaving the hook pending the result.
2. Once the approval is granted, the hook notification is sent through the channel.
3. If the approval is denied, the hook is not sent and remains in a `cancelled` state.

## Common use cases

### Ensuring application configuration

When creating an application, you may need to set up specific configurations, such as AWS accounts or Kubernetes clusters, to ensure future scopes and deployments function correctly.

A hook lets you enforce these configurations before the repository is created and before the application becomes available to developers. Without hooks, the application could become available before the required configurations are in place, potentially causing errors when creating scopes.

A before-hook can also hand configuration back to the application, such as the repository it should be created in. See [Updating the entity from the hook](./setup#updating-the-entity-from-the-hook).

### Managing deployment-related infrastructure

Some deployments require infrastructure not managed directly by nullplatform. For example, if a scope has a custom domain, a hook can verify that the domain exists and is properly configured before the deployment starts.

## Next steps

- [Set up entity hooks](./setup): configure a notification channel, create a hook action, and implement the callback handler.
- [Conditional firing](./filters): narrow which events reach your endpoint by adding a `filters` expression to the notification channel.
- [Entity hook API](/docs/entity-hook-api-index): the full endpoint reference for hook actions and hook requests.

## Tutorials

- [Automatically update application repositories on creation](/docs/tutorials/modify-repository-on-create): use a before-hook on `application:create` to add files to every new repo automatically.
- [Notify when a deployment fully shifts traffic](/docs/tutorials/notify-on-deployment-traffic-shift): combine an after-hook with a channel filter to run logic only once a deployment reaches 100% traffic.