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
phoneChanged	After phone number change	No	Alert the account email, flag removed SMS MFA devices
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 registration order. In NestJS that is the order they are listed in NAuthHooksModule.forFeature():

// NestJS - array order is execution order
NAuthHooksModule.forFeature([
  EmailNotificationHook, // Executes first
  AnalyticsHook, // Executes second
  CrmSyncHook, // Executes last
]);

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

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
`IPhoneChangedHook`	Phone changed hook interface	IPhoneChangedHook
`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()
`@PhoneChangedHook()`	Phone changed hook decorator	@PhoneChangedHook()
`@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

How Hooks Work​

Available Hooks​

User Lifecycle Hooks​

Security & Authentication Hooks​

Account Management Hooks​

Hook Behavior​

Blocking vs Non-Blocking​

Execution Order​

Error Handling​

API Reference​

Interfaces​

Services​

NestJS Decorators​

What's Next​