Notification System

Relevant source files

• cmd/intercmd.go
• cmd/serve_nonwindows.go
• cmd/serve_windows.go
• cmd/version.go
• cmd/winsc_nonwindows.go
• cmd/winsc_windows.go
• internal/app/app.go
• internal/domain/dtos/notify.go
• internal/notify/service.go
• internal/rest/handlers/notifications.go
• internal/rest/handlers/workflows.go
• internal/rest/routes/routes.go
• internal/scheduler/scheduler.go
• internal/tools/ftp/client.go
• internal/tools/ftp/config.go
• internal/tools/ftp/file.go
• internal/tools/s3/client.go
• internal/tools/smtp/client.go
• internal/tools/ssh/client.go
• internal/workflow/pbhook.go
• internal/workflow/pbjob.go
• internal/workflow/service_inst.go
• main.go
• pkg/core/certifier/challengers/http01/s3/s3.go
• pkg/core/deployer/providers/wangsu-cdnpro/wangsu_cdnpro.go
• pkg/core/deployer/providers/webhook/webhook.go
• pkg/core/notifier/providers/dingtalkbot/dingtalkbot.go
• pkg/core/notifier/providers/discordbot/discordbot.go
• pkg/core/notifier/providers/email/email.go
• pkg/core/notifier/providers/larkbot/larkbot.go
• pkg/core/notifier/providers/mattermost/mattermost.go
• pkg/core/notifier/providers/slackbot/slackbot.go
• pkg/core/notifier/providers/telegrambot/telegrambot.go
• pkg/core/notifier/providers/webhook/webhook.go
• pkg/core/notifier/providers/wecombot/wecombot.go
• pkg/sdk3rd/matrix/client.go
• pkg/sdk3rd/nginxproxymanager/types.go
• pkg/utils/cert/hostname/hostname_test.go
• pkg/utils/maps/replace.go
• pkg/utils/tls/config.go
• ui/src/components/access/forms/AccessConfigFieldsProviderEmail.tsx

The Notification System in Certimate is a multi-channel alerting subsystem designed to provide real-time updates on certificate renewal status, workflow execution results, and system health. It utilizes a provider-based architecture, allowing for extensible support of various communication platforms including Email, Webhooks, and instant messaging services.

Architecture Overview

The system is structured into three layers:

1. Service Layer (NotifyService): Orchestrates high-level logic, such as the test-push functionality and integration with the repository layer to fetch credentials internal/notify/service.go15-17
2. Dispatching Layer (notifiers.Registries): A registry-based factory that maps provider types to their specific implementations and handles the population of configuration structs from generic maps.
3. Provider Layer (notifier.Provider): The low-level implementation for each specific channel (e.g., SMTP for Email, HTTP for Webhooks) pkg/core/notifier/providers/email/email.go45-48

Notification Data Flow

The following diagram illustrates the flow of a notification request from the API or a Workflow Node through to the final delivery.

Notification Delivery Flow

Sources: internal/notify/service.go25-45 pkg/core/notifier/providers/email/email.go71-110 internal/notify/service.go15-17

The NotifyService

The NotifyService acts as the primary entry point for manual notification triggers, such as the "Test Push" feature in the UI. It depends on an accessRepository to retrieve stored credentials associated with a specific Access record internal/notify/service.go15-17

Test Push Implementation

When a user requests a test notification:

1. The service retrieves the Access record by ID via n.accessRepo.GetById internal/notify/service.go27
2. It verifies the access record is intended for notifications (checked via the Reserve field set to "notif") internal/notify/service.go30-31
3. It constructs a SendNotificationRequest with a default subject [Certimate] Notification Testing and message Welcome to use Certimate! internal/notify/service.go11-12 internal/notify/service.go38-44
4. It invokes the NotifyClient via NewClient() to dispatch the message internal/notify/service.go37-45

Sources: internal/notify/service.go25-50

Provider Interface and Registration

Every notification channel must implement the notifier.Provider interface. This ensures a consistent contract for the dispatcher regardless of the underlying protocol.

Interface Definition

The interface requires a Notify method and a SetLogger method for observability:

• Notify(ctx, subject, message): Executes the actual delivery. For example, the Email provider uses smtp.Client to send the message pkg/core/notifier/providers/email/email.go71-82 pkg/core/notifier/providers/email/email.go105
• SetLogger(logger): Allows the workflow engine to inject node-specific logging pkg/core/notifier/providers/email/email.go63-69

Registration Pattern

Providers are registered in the internal/notify/notifiers package. This registers a factory function that transforms generic configuration maps into concrete provider instances using xmaps.Populate.

Code to Entity Mapping: Email Provider Initialization

Sources: pkg/core/notifier/providers/email/email.go19-43 ui/src/components/access/forms/AccessConfigFieldsProviderEmail.tsx11-111 internal/tools/smtp/client.go18-29

Supported Channels

Certimate supports a wide array of notification channels. Each channel is defined by a NotificationProviderType. Note that Bark, Gotify, ServerChan, Pushover, and PushPlus are not present in the current implementation; Matrix and Mattermost are supported.

Channel	Implementation Detail	Configuration Key Examples
Email	SMTP client with HTML/Plain support	smtpHost, smtpPort, username, senderAddress pkg/core/notifier/providers/email/email.go19-43
Webhook	Generic HTTP with configurable methods	webhookUrl, method, headers, webhookData pkg/core/notifier/providers/webhook/webhook.go26-41
Telegram	Telegram Bot API	botToken, chatId pkg/core/notifier/providers/telegrambot/telegrambot.go21-25
DingTalk	Robot Webhook with Sign support	webhookUrl, secret pkg/core/notifier/providers/dingtalkbot/dingtalkbot.go27-35
Lark/Feishu	Bot Webhook with Sign support	webhookUrl, secret pkg/core/notifier/providers/larkbot/larkbot.go26-34
WeCom	Enterprise WeChat Bot	webhookUrl pkg/core/notifier/providers/wecombot/wecombot.go21-25
Slack	Incoming Webhook	webhookUrl pkg/core/notifier/providers/slackbot/slackbot.go21-25
Discord	Webhook	webhookUrl pkg/core/notifier/providers/discordbot/discordbot.go21-25
Mattermost	Mattermost API v4	serverUrl, username, password, channelId pkg/core/notifier/providers/mattermost/mattermost.go20-29
Matrix	Matrix Client API (homeserver)	serverUrl, accessToken, roomId pkg/sdk3rd/matrix/client.go23-55

Mattermost Provider Deep Dive

The Mattermost provider (pkg/core/notifier/providers/mattermost) interacts with the Mattermost API v4:

• Authentication: Performs a login request to /api/v4/users/login using Username and Password to obtain a session token from the Token header pkg/core/notifier/providers/mattermost/mattermost.go67-80
• Message Posting: Uses the session token to post a message to /api/v4/posts. The message is structured as an attachment containing the subject as the title and message as the text pkg/core/notifier/providers/mattermost/mattermost.go83-102

Matrix Provider Deep Dive

The Matrix provider uses a custom SDK client (pkg/sdk3rd/matrix) to communicate with Matrix homeservers:

• Discovery: Automatically attempts to resolve the base URL via .well-known/matrix/client if a server URL is provided pkg/sdk3rd/matrix/client.go67-84
• Transactions: Generates unique transaction IDs for message idempotency using rand.Read and timestamps pkg/sdk3rd/matrix/client.go86-90

Email Provider Deep Dive

The Email provider (pkg/core/notifier/providers/email) uses an internal SMTP tool to send messages. It supports:

• TLS/SSL: Configurable via SmtpTls and AllowInsecureConnections. It uses xtls.NewInsecureConfig() when skipping verification pkg/core/notifier/providers/email/email.go25-42 internal/tools/smtp/client.go80
• Message Formats: Supports MESSAGE_FORMAT_PLAIN and MESSAGE_FORMAT_HTML. For HTML messages, it uses bluemonday to sanitize the content and provides a plain-text alternative pkg/core/notifier/providers/email/email.go88-96
• Sender Aliases: Allows defining a display name (e.g., SenderName) pkg/core/notifier/providers/email/email.go98-102

Bot Implementation (Lark/DingTalk)

Instant messaging bots support variable replacement and security signatures.

• Variable Replacement: The system replaces ${CERTIMATE_NOTIFIER_SUBJECT} and ${CERTIMATE_NOTIFIER_MESSAGE} within the JSON payload before sending pkg/core/notifier/providers/larkbot/larkbot.go94-98
• Lark/Feishu Signature: Calculates an HMAC-SHA256 signature using a timestamp and secret to secure the webhook pkg/core/notifier/providers/larkbot/larkbot.go101-116

Sources: pkg/core/notifier/providers/email/email.go71-110 pkg/core/notifier/providers/larkbot/larkbot.go68-139 pkg/core/notifier/providers/mattermost/mattermost.go63-105 pkg/sdk3rd/matrix/client.go23-55 internal/tools/smtp/client.go64-112

Notification Templates

Notifications in workflows (the bizNotify node) support templating. The UI allows configuring specific provider settings and message content.

Common template variables (processed by the provider implementations) include:

• ${CERTIMATE_NOTIFIER_SUBJECT}: The subject line of the notification.
• ${CERTIMATE_NOTIFIER_MESSAGE}: The body content of the notification.
• ${SUBJECT} / ${MESSAGE}: Legacy compatibility variables pkg/core/notifier/providers/larkbot/larkbot.go97-98

Sources: pkg/core/notifier/providers/larkbot/larkbot.go94-98

Test-Push API

The backend exposes a dedicated endpoint for testing notification configurations before they are used in production workflows.

• Endpoint: POST /api/notifications/test-push
• Request DTO: NotifyTestPushReq containing Provider and AccessId internal/domain/dtos/notify.go7-10
• Logic:
  1. The handler calls NotifyService.TestPush internal/notify/service.go25
  2. The service fetches the Access configuration from the database and validates it is a notification access (access.Reserve == "notif") internal/notify/service.go27-32
  3. A temporary notifier.Provider is instantiated via NewClient() internal/notify/service.go37
  4. A message with subject [Certimate] Notification Testing and message Welcome to use Certimate! is dispatched internal/notify/service.go11-12 internal/notify/service.go42-43

Sources: internal/notify/service.go25-50 internal/domain/dtos/notify.go7-13