Notifications

The Notifications page surfaces the most important auth events from your audit log in a focused, actionable view. Instead of sifting through thousands of audit entries, notifications filter down to the events that matter — new users, security changes, organization activity, and key management.

How Notifications Work

1. Auth events occur (sign-ups, password changes, MFA, org changes, etc.)
2. Events are recorded in the audit log (30+ event types)
3. The notifications view filters for "important" events only
4. Important events are displayed in reverse chronological order
5. Each notification shows the action, actor, and relative timestamp

Notifications are a filtered view of the audit log — not a separate system. This means every notification is also visible in the full Audit Logs view, and all audit log features (export, search, pagination) apply.

Important Events

Notifications filter the audit log to these high-signal event types:

These events were selected because they represent state changes that administrators should be aware of — new accounts, security posture changes, organizational changes, and infrastructure changes.

Important: The notification filter uses substring matching. For example, the filter user.created will match both user.created and any future event containing that string.

Notification Data Model

Each notification is an audit event with this structure:

interface AuditEvent {
  id: string;
  action: string;          // e.g., "user.created"
  occurredAt: string;      // ISO 8601 timestamp
 
  actor: {
    type: string;          // "user", "admin", "system", "api_key"
    id: string;
    email?: string;
    name?: string;
  };
 
  target: {
    type: string;
    id: string;
    email?: string;
    name?: string;
  };
 
  context: Record<string, unknown>;
}

See Audit Logs for the complete event structure documentation.

Viewing Notifications in the Dashboard

1. Navigate to Notifications in the dashboard sidebar
2. Recent important events are displayed as a list

Notification Display

Each notification row shows:

• Action badge — The event type displayed as a badge (e.g., user.created, password.changed)
• Actor — Who performed the action, shown as their name, email, or ID (in order of availability)
• Timestamp — Relative time (e.g., "2 minutes ago", "3 hours ago", "yesterday")

Empty State

When no important events have occurred, the page shows:

"No notifications. You're all caught up. Check back later for updates."

Backend: No Separate Endpoints

Notifications reuse the existing audit log endpoint — no additional backend endpoints are needed:

The filtering from audit events to notifications happens client-side in the dashboard. The audit log endpoint returns all events, and the notifications page filters to important ones.

Customizing Important Events

The set of important events is defined in the dashboard page source. To customize which events appear as notifications, modify the IMPORTANT_ACTIONS array:

const IMPORTANT_ACTIONS = [
  "user.created",
  "user.deleted",
  "password.changed",
  "mfa.enabled",
  "organization.created",
  "organization.deleted",
  "member.invited",
  "member.removed",
  "api-key.created",
  "webhook.created",
];

Add or remove event types to match your application's notification needs. Any valid audit log action can be included.

Relative Time Formatting

Notifications display timestamps as human-readable relative time:

Notifications vs. Audit Logs

For comprehensive event querying, filtering, and export, use Audit Logs.

Using the Audit Log API for Notifications

If you're building a custom notification UI outside the dashboard, use the audit log SDK methods:

import { BanataAuth } from "@banata-auth/sdk";
 
const banata = new BanataAuth({
  apiKey: "your-api-key",
  baseUrl: "https://your-deployment.convex.site",
});
 
// Fetch recent events
const { data: events } = await banata.auditLogs.listEvents({
  limit: 50,
});
 
// Filter to important events client-side
const IMPORTANT_ACTIONS = [
  "user.created",
  "user.deleted",
  "password.changed",
  "mfa.enabled",
  "organization.created",
  "organization.deleted",
  "member.invited",
  "member.removed",
  "api-key.created",
  "webhook.created",
];
 
const notifications = events.filter((event) =>
  IMPORTANT_ACTIONS.some((action) => event.action.includes(action))
);

Webhook-Based Notifications

For real-time push notifications (email, Slack, PagerDuty), use Webhooks instead of polling the audit log:

// Register a webhook for important events
const endpoint = await banata.webhooks.createEndpoint({
  url: "https://myapp.com/api/notifications",
  events: [
    "user.created",
    "user.deleted",
    "password.changed",
    "organization.created",
    "member.removed",
  ],
});

This gives you server-push notifications without polling.

Security Considerations

1. Admin-only access — The notifications page and the underlying audit log endpoint require admin authentication.
2. No sensitive data exposed — Notifications show event types, actor identities, and timestamps — never passwords, tokens, or secrets.
3. Audit trail integrity — Notifications are a read-only view. Audit events cannot be modified or deleted through the notification interface.

Troubleshooting

"No notifications" but events are occurring

1. Check that the events match the IMPORTANT_ACTIONS list. Common auth events like session.created are intentionally excluded — they're too frequent to be useful as notifications.
2. Verify that audit logging is working by checking the full Audit Logs page.
3. Ensure you're signed in as an admin.

"Failed to load notifications"

The audit log endpoint may be unreachable. Check that the Convex backend is running and that your session is valid.

"Timestamps showing 'Invalid Date'"

Ensure the audit events have valid occurredAt timestamps. This can happen if custom audit events are created with malformed date strings.

What's Next

• Audit Logs — Full audit trail with filtering, search, and export
• Webhooks — Push notifications for auth events
• Radar & Bot Protection — Monitor and block suspicious activity