> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding rules with hooks

> Use hooks to check your own rules before your Base44 app saves data, lets someone sign up, runs an integration or passes a message to one of its in-app agents.

Hooks are a type of workflow, and you find them with your other workflows on your app's **Workflows** page. They let you decide what happens before your app takes certain actions, such as saving a record or letting someone sign up. A hook checks your rules, then allows or blocks the action. Use hooks to keep your data correct, control who gets into your app and give your in-app agents the right information, without writing code yourself.

> [!WARNING]
>
> **What you need to use hooks:**
>
> * **Rollout:** Hooks are rolling out gradually, so you may not see them yet.
> * **Plan:** You need a [Builder plan](https://base44.com/pricing) or higher to use hooks.

![The Workflows page with an active Before data is saved hook, Require Delivery Address, above a regular workflow](https://mintcdn.com/base44/4q492Ye6WqsFD8-P/images/apps-workflows-hook-in-list.png?fit=max\&auto=format\&n=4q492Ye6WqsFD8-P\&q=85\&s=0e76770e28c780882b3a38e650d812c3)

A hook on the Workflows page

> [card] What can I use hooks for?
>
> Some examples of rules you can build with hooks:
>
> * **Protect data changes:** Only let managers change an approved amount, or don't let anyone complete a task that has no owner.
> * **Control who joins:** Only let people with your company email sign up, and give them the right role as they join.
> * **Control integration use:** Only let paying members use built-in integrations, such as AI actions.
> * **Give agents context:** Check the first message of a conversation with an in-app agent, and add details the agent uses in its replies.

***

## How hooks work

A hook is a type of workflow that runs just before an action in your app. Your app waits for its answer, then lets the action go ahead or stops it.

* **Its answer:** Every hook returns **Allowed** or **Blocked**. Some also return extra details, such as a new person's role or context for an in-app agent.
* **When it blocks:** The person sees the message you set in your rule, or a general message if you didn't set one.
* **Outside information:** Most hooks can call a backend function, for example to check an internal directory. The **Before data is saved** hook can only check conditions and calculations, so saving stays fast.
* **Changes from code:** The **Before data is saved** hook also runs when a backend function changes data, not only your app's pages.

> [!WARNING]
>
> If a hook fails or takes too long, your app blocks the action. Before you rely on a new hook, [check its logic and first runs](#checking-a-hook), so a mistake in a rule doesn't stop people from using your app.

***

## Choosing a hook

Each hook runs before a different action in your app. When you describe a rule to the AI chat, it picks the right one for you, but knowing them helps you describe what you want.

| Hook | Runs | If it fails or takes too long |
| - | - | - |
| **Before data is saved** | Every time a record is created or updated | The record isn't saved |
| **Before signup** | Every time someone new signs up | The signup is blocked |
| **Before first access** | The first time a signed-in person opens your app | They can't open your app |
| **Before integration use** | Every time someone uses a built-in integration, including AI actions | The request is blocked |
| **Before a conversation starts** | On the first message of each in-app agent conversation | The conversation doesn't start |
| **Before each user message** | On every message sent to an in-app agent | The message doesn't reach the agent |

The signup and first access hooks can also set the person's role or other details. The conversation hook adds information the agent uses for the whole conversation, and the message hook adds information for that reply only.

> [!NOTE]
>
> Some hooks only appear when your app needs them. You see the signup and first access hooks only if your app requires login, and the conversation and message hooks only if your app has an [in-app agent](https://docs.base44.com/Building-your-app/AI-agents-for-apps.md).

***

## Creating a hook

You create a hook the same way as any workflow, by describing what you want in the AI chat. The AI builds the hook, asks any questions it needs and adds it to your **Workflows** list.

### Describing your rule

Describe your rule in plain words, and the AI picks the right hook for you. For example:

```text theme={null}
Before a task is saved as complete, check that it has an owner. If it doesn't, block the save and show "Add an owner before you complete this task."
```

```text theme={null}
Only let people with an @northwind.com email sign up. Give them the Member role.
```

**To create a hook from the AI chat:**

1. Go to your app editor.
2. Describe the rule in the AI chat, then send it.
3. Answer any follow-up questions the AI asks.

### Choosing the action first

Start on the **Workflows** page when you know which action you want to check, such as saving a record. When you choose the action, the AI chat opens with a prompt started for you to finish.

**To create a hook from the Workflows page:**

1. Go to your app editor.
2. Click **Dashboard**.
3. Click **Workflows**.
4. Click **Create workflow**.
5. Click **Add starting point**.
6. Under **Hooks**, choose the action to check, such as **Before data is saved**.
7. Add your rule to the prompt in the AI chat, then send it.
8. Answer any follow-up questions the AI asks.

![The Add starting point menu scrolled to the Hooks section, with Before data is saved outlined](https://mintcdn.com/base44/4q492Ye6WqsFD8-P/images/apps-workflows-hooks-menu.png?fit=max\&auto=format\&n=4q492Ye6WqsFD8-P\&q=85\&s=b610ec9221998e03fa99200f7f8f348c)

Choosing a hook as the starting point

***

## Checking a hook

Before you rely on a hook, check that it does what you meant. You can read its logic and test it with real data. To review its runs, see [monitoring runs](https://docs.base44.com/Building-your-app/managing-workflows.md#monitoring-runs). To turn it off or archive it, see [managing workflows](https://docs.base44.com/Building-your-app/managing-workflows.md#changing-a-workflow).

### Reading a hook's logic

Open a hook from your list of workflows to see it as a diagram, from the action it checks through each condition to the result. Click a step to see its details. A condition step shows what it checks, and a result step shows its decision, **Allowed** or **Blocked**, and the message people see.

![A hook diagram with the Block order step selected, showing its message and the Blocked decision in the details panel](https://mintcdn.com/base44/4q492Ye6WqsFD8-P/images/apps-workflows-hook-diagram.png?fit=max\&auto=format\&n=4q492Ye6WqsFD8-P\&q=85\&s=a3dbe0bc71f2cd8b13909ebd048cfc59)

Reading a hook's logic

### Testing a hook

Test a hook to see how it responds to data from one of its previous runs, using its current rules. The hook needs to run at least once before you can test it. When the test starts, the hook's diagram opens on the test run, so you can see whether it allowed or blocked the action. On the **Activity** tab, test runs are labeled **Test**.

> [!WARNING]
>
> Testing doesn't run the action the hook protects, such as saving the record. Backend functions the hook calls do run, so they can change real data or contact outside services.

**To test a hook:**

1. Go to your app editor.
2. Click **Dashboard**.
3. Click **Workflows**.
4. Click the hook to open it.
5. Click **Run now** in the details panel.
6. In the dialog, choose a previous run to use as the test data.
7. Click **Run test**.

![The Test hook with previous data window with a previous run selected and the Run test button outlined](https://mintcdn.com/base44/4q492Ye6WqsFD8-P/images/apps-workflows-hook-test-dialog.png?fit=max\&auto=format\&n=4q492Ye6WqsFD8-P\&q=85\&s=75872758b2837c1a3513f76eec332907)

Testing a hook with previous data


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.