Notifications

FleetQ keeps you informed about important platform events through in-app notifications and email alerts. Notifications are team-scoped — every team member receives events relevant to their work — and each user can independently configure which notification types they want and how they are delivered.

Notification types

The table below lists every notification FleetQ can send, when it fires, and its default delivery channels.

Type	When it fires	Default channels
Experiment transitions	When an experiment changes state — especially on failures such as `ScoringFailed`, `PlanningFailed`, or `Killed`	In-app, Email
Approval requests	When a workflow node or experiment stage requires human approval before continuing	In-app, Email
Budget alerts	When team credit spend reaches 80% or 100% of the configured budget	In-app, Email
Project completions/failures	When a project run finishes successfully (`completed`) or fails (`failed`)	In-app, Email
Milestone reached	When a project milestone is marked as completed	In-app
Usage alerts	When monthly usage (experiment runs, outbound sends) approaches or exceeds plan limits — triggered at 80% and 100%	In-app, Email
Weekly digest	A summary of team activity sent every Monday at 09:00 — experiments run, credits used, approvals pending	Email
Welcome	Sent to new users upon first login to guide them through onboarding	In-app, Email

Notification bell

The bell icon in the application header shows a live unread count badge. Clicking it opens a dropdown with your most recent notifications, each showing its type, a short description, and a timestamp. Notifications are marked as read automatically when you click through to the referenced entity (experiment, approval, project, etc.).

The unread badge updates in real time via Livewire — no page refresh needed. If you have many pending approvals, the bell is the fastest way to jump directly to the approval inbox.

Notification inbox

The full notification history is available at /notifications. From the inbox you can:

View all notifications with their full message and timestamp.
Mark individual notifications as read, or mark all as read at once.
Filter the list by notification type (e.g., show only budget alerts).
Click through to the source entity directly from the notification row.

Notification preferences

Each user can configure which notifications they receive and how they are delivered at /notifications/preferences. For each notification type you can choose:

Option	Behaviour
In-app only	Notifications appear in the bell and inbox, but no email is sent.
Email only	Notifications are sent by email but do not appear in the in-app inbox.
Both	Default. Notifications are delivered via both channels.
None	Disable this notification type entirely for your account.

Preferences are per-user, not per-team. Each team member manages their own delivery settings independently. Team owners and admins cannot override individual member preferences.

Contacts & channels

FleetQ has a contact system for managing external notification recipients — people or entities outside your team that should receive automated outbound messages. Contacts are separate from team member notifications and are used primarily by outbound connectors and signal routing.

Model	Purpose
ContactIdentity	Represents an external person or entity — for example, a lead, customer, or partner. Stores name, type, and optional metadata. Browse contacts at /contacts.
ContactChannel	Defines how to reach a contact — a delivery channel such as email address, Telegram chat ID, or Slack user/channel. Each contact can have multiple channels. FleetQ uses the appropriate channel when dispatching outbound messages.

Contacts are resolved at delivery time by ContactResolver, which matches outbound proposals to the correct channel for each recipient. When a signal arrives containing a known contact identifier, trigger rules can route it directly to that contact's preferred channel.

MCP tools

The following MCP tools are available for notification management via the AgentFleetServer:

Tool	What it does
notification_manage	List notifications (with optional unread filter), mark one or all as read, and read or update per-type notification preferences for the current user.

bash

# List the 10 most recent unread notifications
notification_manage action=list unread=true limit=10

# Mark all notifications as read
notification_manage action=mark_all_read

# Read current notification preferences
notification_manage action=get_preferences

# Disable email for budget alerts
notification_manage action=update_preferences type=budget_alert channel=email enabled=false

Webhook notifications

In addition to in-app and email notifications, you can configure outbound webhook endpoints to receive platform events as HTTP POST payloads. This allows integrating FleetQ event streams with external systems such as Slack, PagerDuty, or custom dashboards.

Webhook endpoints are managed at the team level. Each endpoint has a target URL, optional HMAC secret for payload verification, and a list of event types to subscribe to.

FleetQ signs each outbound webhook request with an X-FleetQ-Signature header (HMAC-SHA256 of the raw JSON body using your endpoint secret). Always verify this signature on your receiving server before processing the payload.

Webhook MCP tools

Tool	What it does
webhook_list	List all configured webhook endpoints for the team.
webhook_create	Create a new webhook endpoint with a target URL, secret, and event subscriptions.
webhook_update	Update an existing webhook endpoint — change URL, secret, active status, or subscribed events.
webhook_delete	Delete a webhook endpoint and stop all event delivery to that URL.

API reference

Notification state and webhook configuration are accessible via the REST API. Full request/response schemas are available in the OpenAPI 3.1 reference.

Notification endpoints

Method + Path	Purpose
GET /api/v1/notifications	List notifications for the authenticated user (cursor-paginated).
POST /api/v1/notifications/{id}/read	Mark a single notification as read.
POST /api/v1/notifications/read-all	Mark all unread notifications as read.
GET /api/v1/notifications/preferences	Get the current user's notification preferences.
PUT /api/v1/notifications/preferences	Update notification preferences for one or more notification types.

Webhook endpoints

Method + Path	Purpose
GET /api/v1/webhooks	List all webhook endpoints for the team.
GET /api/v1/webhooks/{id}	Get details for a single webhook endpoint.
POST /api/v1/webhooks	Create a new webhook endpoint.
PUT /api/v1/webhooks/{id}	Update a webhook endpoint's configuration.
DELETE /api/v1/webhooks/{id}	Delete a webhook endpoint.

bash

# Create a webhook endpoint that receives experiment failure events
curl -X POST https://fleetq.169.58.89.204.sslip.io/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/fleetq",
    "secret": "your-webhook-secret",
    "events": ["experiment.failed", "budget.alert", "approval.requested"]
  }'