Notification Plugin

Multi-channel notifications via Herald bridge with event-driven templates for email, SMS, and in-app messaging.

The notification plugin provides a unified multi-channel notification system for Authsome. It replaces the legacy email plugin with Herald bridge integration, supporting email, SMS, push, and in-app notifications from a single configuration. Notifications are triggered automatically by authentication lifecycle events.

Setup

import (
    "github.com/xraph/authsome"
    "github.com/xraph/authsome/plugins/notification"
)

eng, err := authsome.NewEngine(
    authsome.WithStore(store),
    authsome.WithHerald(heraldBridge),
    authsome.WithPlugin(notification.New(notification.Config{
        AppName:       "My App",
        BaseURL:       "https://example.com",
        DefaultLocale: "en",
        Async:         true,
    })),
)

Configuration

Option	Type	Default	Description
`AppName`	`string`	`"AuthSome"`	Application name used in notification templates
`BaseURL`	`string`	`""`	Root URL for building links in notifications
`DefaultLocale`	`string`	`"en"`	Default locale for template rendering
`Async`	`bool`	`false`	Send notifications asynchronously via Dispatch
`Mappings`	`map[string]*Mapping`	default mappings	Override or disable hook-to-notification mappings

Implemented interfaces

Interface	Purpose
`Plugin`	Base plugin identity (`"notification"`)
`OnInit`	Captures Herald bridge, hook bus, and logger; registers global hook handler
`AfterSignUp`	Sends welcome notification to new users
`AfterUserCreate`	Sends verification notification to unverified users

Default notification mappings

The plugin maps authentication events to Herald templates:

Event	Template	Channels	Description
`auth.signup`	`auth.welcome`	email, inapp	Welcome notification on sign-up
`user.create`	`auth.email-verification`	email	Email verification request
`auth.password_reset`	`auth.password-reset`	email	Password reset link
`auth.password_change`	`auth.password-changed`	email, inapp	Confirmation of password change
`org.invitation.accept`	`auth.invitation`	email, inapp	Organization invitation
`auth.mfa.enroll`	`auth.mfa-code`	sms	MFA enrollment code
`auth.account_locked`	`auth.account-locked`	email, inapp	Account lockout notification

Customizing mappings

Override default mappings or add new ones:

notification.New(notification.Config{
    AppName: "My App",
    BaseURL: "https://example.com",
    Mappings: map[string]*notification.Mapping{
        // Override the welcome template
        "auth.signup": {
            Template: "custom.welcome",
            Channels: []string{"email", "sms", "inapp"},
            Enabled:  true,
        },
        // Disable password change notifications
        "auth.password_change": nil,
        // Add a custom event mapping
        "custom.event": {
            Template: "custom.event-template",
            Channels: []string{"inapp"},
            Enabled:  true,
        },
    },
})

Setting a mapping to nil disables notifications for that event.

Event-triggered notifications

The plugin uses two mechanisms to trigger notifications:

Direct plugin hooks

For AfterSignUp and AfterUserCreate, the plugin receives the user object directly and builds the notification:

func (p *Plugin) OnAfterSignUp(ctx context.Context, u *user.User, _ *session.Session) error {
    return p.herald.Notify(ctx, &bridge.HeraldNotifyRequest{
        Template: "auth.welcome",
        Channels: []string{"email", "inapp"},
        To:       []string{u.Email},
        Data:     map[string]any{"user_name": u.Name, "app_name": p.config.AppName},
    })
}

Global hook handler

For all other mapped events, the plugin registers a handler on the global hook bus during OnInit. When any hook event fires, the handler checks if a mapping exists and sends the notification:

p.hooks.On("herald-notification", func(ctx context.Context, event *hook.Event) error {
    return p.handleHookEvent(ctx, event)
})

Events handled by direct hooks (auth.signup, user.create) are skipped in the global handler to avoid duplicates.

Integration with Herald bridge

The Herald bridge provides the notification delivery interface:

type Herald interface {
    Notify(ctx context.Context, req *HeraldNotifyRequest) error
}

type HeraldNotifyRequest struct {
    AppID    string
    Template string
    Channels []string
    To       []string
    UserID   string
    Locale   string
    Async    bool
    Data     map[string]any
}

Direct notification methods

The plugin exposes methods for the engine to call directly:

Password reset notification

err := notificationPlugin.SendPasswordReset(ctx, email, name, resetURL)

Invitation notification

err := notificationPlugin.SendInvitation(ctx, email, inviterName, orgName, acceptURL)

Template data

Each notification includes template data that Herald uses for rendering:

Variable	Description
`user_name`	User's display name or email
`app_name`	Application name from config
`login_url`	Login page URL
`verify_url`	Email verification URL
`reset_url`	Password reset URL
`accept_url`	Invitation accept URL
`expires_in`	Token expiry description
`inviter_name`	Name of the person who sent the invitation
`org_name`	Organization name

Async delivery

When Async: true, notifications are queued via the Dispatch bridge for background delivery. This prevents notification failures from blocking authentication operations. Synchronous mode (default) sends notifications inline and logs warnings on failure.

Notification Plugin

On this page