SIGNALS Docs
Reader View

Notification delivery internals

How the notification engine resolves channels, the channel provider registry, broadcast payload limits, replay guards, email layout resolution, and the notification and draft APIs.

Overview

This is the engine reference behind Notifications & Comms. The Notification & Communication Engine delivers multi-channel notifications (database, email, broadcast) with a three-layer resolution pipeline: system defaults → tenant settings → account preferences. Customer billing communications persist to communication_log with opt-out and unsubscribe support.

Channel provider registry

Channels register through a provider registry:

Built-in channel Purpose
Database In-app notification records
Email Queued SMTP/email driver delivery
Broadcast Real-time via Reverb

Reverb enforces a 10 KB limit per broadcast event, so Signals caps and slims every real-time notification payload. Broadcasts are lightweight envelopes; clients fetch authoritative details on demand instead of receiving full models, bodies, HTML, or exception context.

Plugins can register additional channel providers via the Plugin SDK.

Test a provider configuration: POST /api/v1/channel_providers/{channel_provider}/test.

Three-layer resolution

  1. System default — the seeded available and default channels for each notification type
  2. Tenant setting — company defaults on /admin/settings/notifications (Company defaults tab)
  3. Account override — each person's preferences on /settings/notifications or via the API

Company settings may explicitly opt into an installed plugin channel in addition to narrowing core defaults. Personal preferences only remove channels from the company selection. Installation alone never enables a plugin channel. A channel whose delivery driver is not registered (for example, a disabled plugin) is dropped.

Event→notification wiring includes a replay guard so projection replays do not duplicate sends.

In-app notification bodies

The header notification bell loads database notifications and refreshes on open. Real-time updates arrive via Reverb on the user's private channel. Event-specific bodies replace generic placeholders.

Email layout resolution

Every outbound email is wrapped in a branded layout — the document shell, styles, header, body slot, and footer — resolved at send time by EmailLayoutRenderer:

  1. the layout picked on the email template, when it is still active;
  2. the active default layout row;
  3. the shipped master layout (EmailLayoutSeeder::masterBodyHtml()), branded from settings or, when the database or settings can't be read, from static defaults (the app name and default palette).

Notifications that fall back to a plain message use App\Notifications\Messages\BrandedMailMessage, which renders through the same layout chain instead of Laravel's stock mail template. An architecture test rejects plain MailMessage in app/.

Layouts themselves are edited at Email Layouts.

Communication draft endpoints

The draft lifecycle and permissions are described in Notifications & Comms → Communication drafts.

Endpoint Purpose
GET /api/v1/communication_drafts List drafts (filter[field][operator] filtering)
GET /api/v1/communication_drafts/{id} Show a draft
POST /api/v1/communication_drafts Compose a draft
POST /api/v1/communication_drafts/{id}/approve Approve, optionally editing first
POST /api/v1/communication_drafts/{id}/discard Reject permanently
POST /api/v1/communication_drafts/{id}/send Deliver an approved draft

Communication log API

Administrators with appropriate permissions can browse dispatched communications — channel, template, recipient, status, and timestamps. Read-only API: Communication Log.

Notification preferences API

Endpoint Purpose
GET/PUT /api/v1/notification_preferences Authenticated user's preferences
GET/PUT /api/v1/accounts/{id}/notification_preferences Account-level preferences (admin)
GET/PUT /api/v1/notification_settings System-wide notification settings

See Notification Preferences API.

Built-in notification catalogue

The following built-in keys identify notification types, not delivery endpoints. A channel driver receives the same ChannelSendData contract for each eligible type. Plugin-defined notification keys extend this catalogue when their packages are installed.

database persists an in-app notification, broadcast delivers its real-time envelope, and mail sends email. The resolver normalizes these to the logical in_app and email channels. The table records original core metadata and defaults. Installing a driver leaves those defaults unchanged. Company administrators can explicitly select an installed plugin channel through notification settings; personal preferences only narrow the company selection. Notification settings responses include installed plugin channels in available_channels. This applies to the common dispatch pipeline, not dedicated authentication, digest or customer-communication mail paths. See Plugin Channel Providers for API examples.

Type key Name Audience Available channels Default channels Native plugin route
user.invited User Invited internal database, mail database, mail Dedicated invitation email
update.failed Update Failed internal database, mail database, mail Common account delivery
search.index_lag Search indexing delayed internal database, mail database Common account delivery
queue.job_failed Queued Job Failed internal database, mail database Common account delivery
password.reset Password Reset internal mail mail Dedicated authentication email
auth.magic_link Magic-Link Sign-In internal mail mail Dedicated authentication email
auth.new_sign_in New Sign-In Notice internal mail mail Dedicated authentication email
notification.digest Notification Digest internal mail mail Dedicated digest email
workflow.internal Workflow Internal Notification internal database, mail database, mail Common account delivery
approval_request Approval Request internal database, mail, broadcast database, mail Common account delivery
approval_outcome Approval Outcome internal database, mail, broadcast database, mail Common account delivery
approval_external_link External Approval Link external mail mail Email-only external approval link
rental.created Rental Created internal database, mail database Common account delivery
rental.confirmed Rental Confirmed both database, mail database, mail Common account delivery
rental.cancelled Rental Cancelled both database, mail database, mail Common account delivery
rental.on_hold Rental On Hold internal database, mail database Common account delivery
rental.checked_out Rental Checked Out both database, mail database, mail Common account delivery
rental.checked_in Rental Checked In internal database, mail database Common account delivery
rental.late_return Late Return internal database, mail database, mail Common account delivery
rental.quote_expiring Quote Expiring both database, mail database, mail Common account delivery
conversation.mentioned Conversation Mention internal database, mail database, mail Common account delivery
shortage.escalated Shortage Escalated internal database, mail database, mail Common account delivery
shortage.acknowledged Shortage Acknowledged internal database, mail database Common account delivery
shortage.resolution.confirmed Shortage Resolution Confirmed internal database, mail database Common account delivery
shortage.waitlist.created Waitlist Monitor Created internal database, mail database Common account delivery
shortage.waitlist.matched Waitlist Match internal database, mail database Common account delivery
shortage.waitlist.expired Waitlist Expired internal database, mail database Common account delivery
virtual_stock.overrun Virtual Stock Overrun internal database, mail database, mail Common account delivery
invoice.created Invoice Created external mail mail Dedicated customer communication
invoice.overdue Invoice Overdue both database, mail database, mail Common account delivery
invoice.payment_received Payment Received both database, mail database, mail Dedicated customer communication
invoice.credit_note Credit Note Issued external mail mail Dedicated customer communication
statement.emailed Account Statement Emailed external mail mail Dedicated customer communication
document.finalised Document Finalised internal database, mail database Common account delivery
document.emailed Document Emailed external mail mail Common account delivery
document.public_link_created Document Public Link Created both database, mail database, mail Common account delivery
document.portal_question Document Portal Question internal database, mail database, mail Common account delivery
document.approved Document Approved internal database, mail database, mail Common account delivery
document.declined Document Declined internal database, mail database, mail Common account delivery
invoice.portal_payment_received Portal Payment Received internal database, mail database, mail Common account delivery
repair.created Repair Created internal database, mail database Common account delivery
repair.updated Repair Updated internal database, mail database Common account delivery
repair.released Repair Released internal database, mail database Common account delivery
equipment_test.completed Equipment Test Completed internal database database Common account delivery
equipment_test.failed Equipment Test Failed internal database, mail database, mail Common account delivery
equipment_test.due Equipment Test Due Soon internal database, mail database, mail Common account delivery
equipment_test.overdue Equipment Test Overdue internal database, mail database, mail Common account delivery
certification.expiring Certification Expiring internal database, mail database, mail Common account delivery
stock_check.closed Stock Check Closed internal database, mail database, mail Common account delivery
flightcase.contents_overrun Flightcase Contents Overrun internal database, mail database, mail Common account delivery
import_batch.committed Import Batch Completed internal database, mail database, mail Common account delivery
import_batch.failed Import Batch Failed internal database, mail database, mail Common account delivery
import_plan.completed Import Plan Completed internal database, mail database, mail Common account delivery
import_plan.undone Import Plan Undone internal database, mail database, mail Common account delivery
export.completed Export Completed internal database, mail database, mail Common account delivery
export.failed Export Failed internal database, mail database, mail Common account delivery
report.scheduled_delivery Scheduled Report Delivered internal database, mail database, mail Common account delivery
report.threshold_alert Report Threshold Reached internal database, mail database, mail Common account delivery
scheduling.conflict_detected Scheduling Conflict Detected internal database, mail database Common account delivery
scheduling.conflict_resolved Scheduling Conflict Resolved internal database, mail database Common account delivery
scheduling.demand_unmet Scheduling Demand Unmet internal database, mail database, mail Common account delivery
scheduling.assignment_confirmed Assignment Confirmed internal database, mail database Common account delivery
scheduling.assignment_cancelled Assignment Cancelled internal database, mail database Common account delivery
scheduling.assignment_rescheduled Assignment Rescheduled internal database, mail database Common account delivery
activity.due_soon Activity due soon internal database, mail database, mail Common account delivery
activity.overdue Activity overdue internal database, mail database, mail Common account delivery

The native-route column distinguishes 56 keys with common account delivery from 10 keys whose listed native delivery remains dedicated. “Common account delivery” means the host can pass account-recipient notifications to an explicitly enabled plugin channel; it does not promise delivery to arbitrary external email addresses. Mixed-audience customer mail and report emails to external addresses retain their email paths. A generic synthetic envelope can be rendered for all 66 keys, including the ten dedicated keys, without establishing native routing for those ten.

Fixed-path notifications

These additional notifications have fixed channels and no selectable notification-type key:

Notification Delivery Purpose
Email verification Email Verify the sign-in address.
Email change requested / confirmation Email Notify the current address and confirm the replacement.
Two-factor authentication reset Email Notify the person when an operator resets their authenticator.
AI embedding budget exceeded In-app and email Alert administrators when monthly usage reaches the configured budget.
Workflow export ready In-app Notify that a workflow export can be downloaded; distinct from the export.completed event.

Customer billing communications use the communication/template path and their corresponding type keys. Digest mail uses notification.digest. Generic domain-event, approval and plugin envelopes reuse existing or plugin-defined type keys. Database/broadcast wrappers and pipeline test notifications are transport or test mechanisms, not additional business types.

For channel contracts, provider configuration, address resolution, and testing, see Plugin Channel Providers.