Notification Plugin

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.

Setup01

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,
    })),
)

Configuration02

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 interfaces03

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 mappings04

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 mappings05

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 notifications06

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 bridge07

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 methods08

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 data09

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 delivery10

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.

← Previous

Phone Plugin

API Key Plugin