# Exit Hooks

> Recipes for what happens when a user deletes their account: delete their files, cancel something at another provider, refuse the deletion, and why every hook must be safe to run twice.

*Canonical: https://makerkit.dev/docs/void-cloudflare/cleanup/exit-hooks*

---

Account deletion calls three kinds of extension points, all in `apps/web/config/account-hooks.config.server.ts` (yours to edit). Pick by *when* the work must happen:

| You want to | Use | Runs | Can stop the delete? |
|---|---|---|---|
| Refuse the delete with a reason | `accountPolicies` | When the code is requested, on **Delete**, and each time the Profile page loads (for the dialog's blockers): keep it cheap and read-only | Yes |
| Do work while the user's rows still exist, or at a provider | `accountDeleteSteps` | After the code, before the transaction | Yes (a denial) |
| Clean up after the account is gone (files, other systems) | `afterAccountDelete` | In the `account.deleted-hooks` job | No: the job retries, then goes dead after its attempts and waits to be replayed ([Running and Failures](./running)) |

Organizations the user deletes with them run through your organization policies, steps and `afterOrganizationDelete` hooks too ([Deleting an Organization](../organizations/deleting)).

## Every Hook Must Be Idempotent

The `account.deleted-hooks` job runs your `afterOrganizationDelete` hooks for each deleted organization, then your `afterAccountDelete` hooks. If one throws, the job fails and the outbox runs the **whole list again from the first hook**. A step runs again if the delete is retried after a refusal. Write each one to be safe to run twice: delete by id (deleting nothing is success), check before you create, key external calls by the user's id.

An account hook gets the user's id only (`{ id }`): the row is gone; an organization hook gets `{ id, name }`. A hook receives `{ signal }` from the job too: pass it to every network or database call so a timed-out attempt stops instead of running beside its retry.

## Recipe: Delete a User's Files

User-owned files in your storage go in an after-hook: the user's rows no longer exist, and the files are named by the user's id.

```ts
import type { AfterAccountDeleteHook } from '@kit/organizations/server';

export const afterAccountDelete: AfterAccountDeleteHook[] = [
  async ({ id }, context) => {
    // an upload kind with `owner: 'user'` is purged by the kit; this is for
    // objects you wrote yourself, under a prefix named by the user's id
    await deleteReports({ userId: id, signal: context?.signal }); // deleting nothing is success
  },
];
```

If your files are an [upload kind](../storage/overview) with `owner: 'user'`, you need no hook: the kit purges them after the delete, like the avatar.

## Recipe: Cancel an External Resource

Work that needs your rows (an id you stored for another provider) goes in a step, before the transaction, while they exist. A denial stops the delete and the user sees your message; the next try runs the step again.

```ts
import { allow, deny } from '@kit/policies';
import type { AccountDeleteStep } from '@kit/organizations/server';

export const accountDeleteSteps: AccountDeleteStep[] = [
  {
    id: 'app.cancel-crm-contact',
    // shown in the dialog's warnings (a translation key), or omit
    warning: async () => 'app.account.crmWarning',
    run: async ({ userId }) => {
      const failed = await removeCrmContact(userId); // idempotent: gone is fine

      return failed
        ? deny({ code: 'CRM_DOWN', message: 'app.account.crmDown' })
        : allow();
    },
  },
];
```

The kit's own step, ending the user's subscription in Stripe, runs first. A step may write; it must not assume it runs once.

## Recipe: Refuse a Deletion

A policy decides from the database whether the user may delete now: a legal hold, an unpaid invoice, an open dispute.

```ts
import { allow, deny } from '@kit/policies';
import { createAccountPolicies, defineAccountPolicy } from '@kit/organizations/server';

export const accountPolicies = createAccountPolicies().registerPolicy(
  defineAccountPolicy({
    id: 'app.legal-hold',
    stages: ['delete'],
    evaluate: async ({ userId }) =>
      (await isOnLegalHold(userId))
        ? deny({
            code: 'LEGAL_HOLD',
            message: 'app.account.legalHold',
            remediation: 'app.account.contactLegal',
            // a path in your app: the remediation becomes a link to it
            remediationHref: '/support',
          })
        : allow(),
  }),
);
```

The message is a translation key in your messages. The kit's own rules (a recent sign-in, the owner rule, the last admin, a live subscription with Stripe off) run first and can't be dropped ([Authorization Policies](../development-guide/authorization-policies)).

## Testing

Call the hook with an id and assert the end state; run the job end to end with `runUntilIdle` ([Testing](./testing)). For retry behaviour, make a hook throw once and assert that it ran twice and the email went out once (`apps/web/config/__tests__/account-deletion.server.test.ts`).

---

**Back:** [Cleanup Overview →](./overview)
