# Add Your Own Audit Events

> Declare an action and a scope type in audit.config.ts and record it from a page action, a cron or a queue job.

*Canonical: https://makerkit.dev/docs/void-cloudflare/audit/adding-actions*

---

Your actions live in `apps/web/config/audit.config.ts`. The kit's own `kit.*` actions are merged in for you; you can't declare one yourself.

## Declare an Action and a Scope Type

A scope type is the kind of owner an event belongs to. `organization` and `user` are built in; add your own (here `project`) in `scopes`:

```ts
import { z } from 'zod';

import { defineAuditConfig } from '@kit/audit';

export const auditConfig = defineAuditConfig({
  scopes: ['project'],
  actions: {
    'project.deleted': {
      scope: 'project',
      severity: 'warning', // info | warning | critical
      metadata: z.object({ fileCount: z.number() }),
    },
    'organization.exported': {
      scope: 'organization',
      severity: 'info',
    },
  },
});
```

Rules, checked when the app starts (and by the types):

- A scope type matches `[a-z][a-z0-9_-]*`, at most 31 characters.
- An action's `scope` is built in or declared in `scopes`.
- Names starting with `kit.` are reserved.
- Metadata is a flat `z.object` of strings, numbers, booleans, enums or literals (optional is fine), at most 1 KB once serialized. Keys called `email`, `ip`, `name`, `phone` or `address`, and email or IP string formats (`z.email()`, `z.string().email()`, `z.ipv4()`…), are refused: ids only. These checks catch honest mistakes; they can't see what a plain `z.string()` holds, so never put a person's details in metadata or in an id.

## Record It

Call `recordAudit` from `#/lib/audit.server.ts` after the write has committed. The actor is the signed-in user (the admin while impersonating); you can't pass one:

```ts
import { defineHandler } from 'void';

import { recordAudit } from '#/lib/audit.server.ts';

export const actions = {
  deleteProject: defineHandler.withValidator({ body: deleteBody })(
    async (c, { body }) => {
      const organization = requireActiveOrganization({ c });
      const { fileCount } = await deleteProject(body.projectId);

      recordAudit({
        c,
        action: 'project.deleted',
        scope: { type: 'project', id: body.projectId },
        target: { type: 'project', id: body.projectId },
        organizationId: organization.id,
        metadata: { fileCount },
      });

      return c.redirect('/projects');
    },
  ),
};
```

For a cron, queue job or webhook there is no session: use `recordSystemAudit({ system: 'nightly-sync', action, scope, metadata })`.

Scope ids and other ids are printable ASCII, at most 64 characters, without `:`. An id of an organization or user scope can't name a different organization or user than the scope.

Record only after the write commits: an event for a rolled-back write would be false. Never put a person's details in metadata.
