notification-platform

NotificationPlatform Guide

Sentry's NotificationPlatform is a provider-based system for sending notifications across Email, Slack, Discord, and MS Teams. You define data + template, register it, and the platform handles rendering and delivery per provider.

Glossary

All paths below are relative to src/sentry/notifications/platform/.

Step 1: Determine Your Operation

After any operation, continue to Step 8 (Test) and Step 9 (Verify).

Step 2: Define the Notification Source

Every notification needs a unique NotificationSource enum value and must be mapped to a NotificationCategory. A NotificationSource should represent the domain or feature that a given notification belongs to.

For examples, load src/sentry/notifications/platform/types.py.

File: types.py

1. Add the enum value under the appropriate category comment:

class NotificationSource(StrEnum):
    # MY_CATEGORY
    MY_NEW_SOURCE = "my-new-source"

2. Add it to NOTIFICATION_SOURCE_MAP under the matching category key:

NOTIFICATION_SOURCE_MAP[NotificationCategory.MY_CATEGORY].append(
    NotificationSource.MY_NEW_SOURCE
)

If no existing NotificationCategory fits, add a new one to the NotificationCategory enum first, then create its entry in NOTIFICATION_SOURCE_MAP.

All NotificationCategory options are defined in the src/sentry/notifications/platform/types.py file.

Step 3: Create the Notification Data

The data class is a frozen dataclass implementing the NotificationData protocol. It carries everything the template needs to render.

File: templates/<your_notification>.py (new file)

from

Rules:

• source is a class variable (no type annotation), not a dataclass field
• Use frozen=True for serialization safety
• Only include fields needed by the template's render() method
• Avoid Django model instances; use primitive types or simple dataclasses for async serialization

For full examples (DataExportSuccess, DataExportFailure), load references/data-and-templates.md.

Step 4: Create the Notification Template

The template converts your data into a provider-agnostic NotificationRenderedTemplate.

Same file as Step 3: templates/<your_notification>.py

Available types:

A notification is composed of sections and text blocks. Text blocks can appear in sections (for the body), and also directly in the subject and footer fields (as list[NotificationTextBlock] instead of plain str).

Sections (portions of a message, used in body):

Text blocks (parts of text — used inside sections, and also in subject and footer):

Refer to src/sentry/notifications/platform/types.py for the full definitions.

Register the import in templates/__init__.py:

This import is required so the @template_registry.register decorator executes at startup (via sentry/notifications/apps.py).

For the full rendered template field reference and more examples, load references/data-and-templates.md.

Step 5: Register Rollout and Send

Rollout registration

The platform uses a tiered rollout system. Each notification source must be added to the appropriate rollout option before it will be delivered.

Rollout options are configured externally in sentry-options-automator (not this repo). The option keys are:

Each option is a Dict mapping source string to rollout rate (0.0-1.0). Example:

These options are registered in src/sentry/options/defaults.py (already done for the four stages above).

Sending pattern

For target types, async/sync decisions, and strategy patterns, load references/targets-and-sending.md.

Step 6: Add a Custom Renderer

Custom renderers bypass the default template-to-renderable conversion for a specific provider + category combination. Use when the default section/block-based rendering is too limiting (e.g., interactive Slack buttons, rich card layouts).

When to use:

• The notification needs provider-specific interactive elements (buttons with action IDs, rich text blocks)
• The rendered output structure differs significantly from subject + body + actions
• You need to render different data types differently within the same provider

How it works: Override get_renderer() on the provider to return your custom renderer class for the relevant category:

File placement: {provider}/renderers/{name}.py (e.g., slack/renderers/seer.py)

For architecture details and the full Seer Slack renderer example, load references/custom-renderers.md.

Step 7: Add a New Provider

Adding a new provider requires implementing the NotificationProvider protocol, a default NotificationRenderer, and registering both. This should only be done when onboarding a new integration provider.

High-level steps:

1. Create {provider_name}/provider.py with provider + default renderer classes
2. Register with @provider_registry.register(NotificationProviderKey.MY_PROVIDER)
3. Add NotificationProviderKey.MY_PROVIDER to the NotificationProviderKey enum in types.py
4. Import the provider in sentry/notifications/apps.py
5. Gate availability behind a feature flag in is_available()

For the full provider scaffold and protocol requirements, load references/provider-template.md.

Step 8: Test

Test directory: tests/sentry/notifications/platform/

Template test

Service integration test

Custom renderer test

If you added a custom renderer, test that the provider dispatches to it:

Step 9: Verify

Pre-flight checklist before submitting:

• NotificationSource enum value added to types.py
• Source added to NOTIFICATION_SOURCE_MAP under correct category
• Data class is @dataclass(frozen=True) with source as class variable
• Template registered with @template_registry.register(DataClass.source)
• Template imported in templates/__init__.py
• example_data on template produces valid output via render_example()
• Rollout option value configured (or ticket filed for sentry-options-automator)
• Sending code guarded with NotificationService.has_access()
• Tests pass: pytest -svv --reuse-db tests/sentry/notifications/platform/
• Pre-commit passes on all modified files