Notifications Guide

Overview

The notification domain is where SYSTEM administrators define delivery channels and the reference data that powers notification configuration forms. Although the caller is a SYSTEM user, the published notification endpoints live under /web/v1/notification-* rather than /web/v1/tenant/*.

What This Domain Covers

1. notification channel type reference data
2. channel querying and operational inspection
3. channel creation and partial updates
4. channel activation and deactivation
5. channel lifecycle state review

Common Prerequisites

1. Authorization: Bearer <accessToken>
2. X-PORTAL-ACCESS-CODE: <system-portal-code>
3. Turnstile token support where the gateway enforces it
4. institution-level permission to manage notification channels

Shared Headers

X-PORTAL-ACCESS-CODE: <system-portal-code>
Authorization: Bearer <accessToken>
Content-Type: application/json

Some deployments also require Turnstile verification on the authenticated notification calls:

X-Turnstile-Token: <turnstile-token>

Common Endpoint Set

1. POST /web/v1/notification-channel-types/query
2. POST /web/v1/notification-channels/query
3. POST /web/v1/notification-channels/command/create
4. POST /web/v1/notification-channels/command/update
5. POST /web/v1/notification-channels/command/activate
6. POST /web/v1/notification-channels/command/deactivate

Typical Operational Sequence

1. load reference channel types and status constants
2. query existing channels for the target institution
3. create a new channel in PENDING
4. update credentials or metadata if validation feedback requires changes
5. activate the channel for production use
6. deactivate the channel during maintenance or incident response

Decision Points

1. whether the UI is reference-data only or needs full channel administration
2. whether the environment wants a channel staged in PENDING or activated immediately after creation
3. whether the target institution reuses an existing email channel or creates a new dedicated one
4. whether Turnstile is enforced on these authenticated endpoints in the target deployment

Error Handling

1. 4010 means the JWT is missing, expired, or not permitted to manage channels
2. 4030 often indicates Turnstile validation failure on the gateway
3. 4040 on update or activate means the channel ID is stale or wrong
4. validation failures typically come from incomplete email configuration
5. never assume a non-ACTIVE channel is ready for delivery even if creation succeeded

Recommended Reading Order

1. start with Channel Operations and Reference Data
2. pair it with institution or account admin flows if ownership and permissions are still being established

Next Steps

1. Channel Operations and Reference Data
2. Account Guide
3. Workspace Guide