Lifecycle Hooks

Lifecycle hooks let you inject custom logic at specific points in the authentication flow --- validation, notifications, integrations, and business logic without modifying core authentication code.

How Hooks Work

Available Hooks

User Lifecycle Hooks

Hook	When	Can Block?	Use Cases
preSignup	Before user creation	Yes	Validation, domain whitelisting, invite codes
postSignup	After user creation	No	Analytics, CRM sync, resource provisioning
onboardingCompleted	When onboarding is complete	No	Welcome emails, onboarding flows, "account ready" notifications
userProfileUpdated	After profile attribute changes	No	CRM sync, analytics tracking, audit logging

Security & Authentication Hooks

Hook	When	Can Block?	Use Cases
passwordChanged	After password change	No	Security alerts, force logout notifications
mfaFirstEnabled	After first MFA device setup	No	Congratulations email, security confirmation
mfaDeviceRemoved	After MFA device deletion	No	Security alerts, backup device reminders
mfaMethodAdded	After MFA method added	No	Security alerts, inventory tracking
adaptiveMfaRiskDetected	When adaptive MFA risk evaluation runs and notifyUser: true	No	Risk alert emails, admin notifications, SIEM logging

Account Management Hooks

Hook	When	Can Block?	Use Cases
accountStatusChanged	After account enable/disable	No	Account disabled notifications, re-enablement confirmations
emailChanged	After email address change	No	Dual notification (old + new email), security alerts
accountLocked	After account lockout	No	Lockout notifications, unlock instructions
sessionsRevoked	After sessions revoked	No	Security alerts, forced logout notifications

Hook Behavior

Blocking vs Non-Blocking

• Blocking Hooks (preSignup): Can throw exceptions to prevent the operation
• Non-Blocking Hooks (all others): Errors are logged but don't affect the operation

Execution Order

Hooks execute in priority order (lower values first). Multiple hooks with the same priority execute in registration order:

// NestJS with decorators
@PasswordChangedHook({ priority: 1 }) // Executes first
export class EmailNotificationHook implements IPasswordChangedHook {}

@PasswordChangedHook({ priority: 2 }) // Executes second
export class AnalyticsHook implements IPasswordChangedHook {}

@PasswordChangedHook() // Default priority 100, executes last
export class CrmSyncHook implements IPasswordChangedHook {}

// Express/Fastify manual registration
hookRegistry.registerPasswordChanged(new EmailNotificationHook());
hookRegistry.registerPasswordChanged(new AnalyticsHook());
hookRegistry.registerPasswordChanged(new CrmSyncHook());
// Registration order determines execution order

Error Handling

Non-blocking hooks catch and log errors automatically:

// Hook throws error → Error logged → Next hook still executes
try {
  await hook.execute(metadata);
} catch (error) {
  logger.error('Hook failed:', error);
  // Continue with next hook
}

API Reference

Interfaces

Interface	Description	Documentation
IPreSignupHookProvider	Pre-signup hook interface	IPreSignupHookProvider
IPostSignupHookProvider	Post-signup hook interface	IPostSignupHookProvider
IOnboardingCompletedHook	Onboarding completed hook interface	IOnboardingCompletedHook
IUserProfileUpdatedHook	User profile updated hook interface	IUserProfileUpdatedHook
IPasswordChangedHook	Password changed hook interface	IPasswordChangedHook
IMFAFirstEnabledHook	MFA first enabled hook interface	IMFAFirstEnabledHook
IMFADeviceRemovedHook	MFA device removed hook interface	IMFADeviceRemovedHook
IMFAMethodAddedHook	MFA method added hook interface	IMFAMethodAddedHook
IAdaptiveMFARiskDetectedHook	Adaptive MFA risk detected hook	IAdaptiveMFARiskDetectedHook
IAccountStatusChangedHook	Account status changed hook interface	IAccountStatusChangedHook
IEmailChangedHook	Email changed hook interface	IEmailChangedHook
IAccountLockedHook	Account locked hook interface	IAccountLockedHook
ISessionsRevokedHook	Sessions revoked hook interface	ISessionsRevokedHook

Services

Service	Description	Documentation
HookRegistryService	Hook registration service	HookRegistryService

NestJS Decorators

note

There is currently no @OnboardingCompletedHook() decorator. If you need custom onboarding-completed behavior in NestJS, register an IOnboardingCompletedHook via HookRegistryService.

Decorator	Description	Documentation
@PreSignupHook()	Pre-signup hook decorator	@PreSignupHook()
@PostSignupHook()	Post-signup hook decorator	@PostSignupHook()
@PasswordChangedHook()	Password changed hook decorator	@PasswordChangedHook()
@MFAFirstEnabledHook()	MFA first enabled hook decorator	@MFAFirstEnabledHook()
@MFADeviceRemovedHook()	MFA device removed hook decorator	@MFADeviceRemovedHook()
@AdaptiveMFARiskDetectedHook()	Adaptive MFA risk detected hook	@AdaptiveMFARiskDetectedHook()
@AccountStatusChangedHook()	Account status changed hook decorator	@AccountStatusChangedHook()
@EmailChangedHook()	Email changed hook decorator	@EmailChangedHook()
@AccountLockedHook()	Account locked hook decorator	@AccountLockedHook()
@SessionsRevokedHook()	Sessions revoked hook decorator	@SessionsRevokedHook()
@UserProfileUpdatedHook()	User profile updated hook decorator	@UserProfileUpdatedHook()
NAuthHooksModule	Hook registration module	NAuthHooksModule

What's Next

• Lifecycle Hooks Guide --- Step-by-step implementation with best practices
• Notifications & Templates --- Built-in email and SMS notification system
• Challenge System --- Understanding authentication flows
• Error Handling --- Exception handling patterns