Rule Hooks

Rule hooks are system events that trigger rule components. Each hook fires at a specific point in a resource's lifecycle, allowing you to validate operations, enforce business logic, or trigger automations.

The hook system is organized into two families:

• Actor Lifecycle Hooks — events tied to the lifecycle of actors (orders, payments, tickets, SKUs, assets)
• Rule Lifecycle Hooks — events tied to the management of rules themselves

Actor Lifecycle Hooks

These hooks fire at specific points in an actor's create/delete/command/journal lifecycle.

Hook Timing

Before Hooks (OnXxxBeforeCreated, OnXxxBeforeDeleted): Execute before the operation completes. Can prevent it with a validation error.

After Hooks (OnXxxCreated, OnXxxDeleted, and state-change hooks like OnPaymentCapture): Execute after the operation completes, once changes are persisted.

Command Hooks (OnXxxCommands): Execute when commands are applied to an actor. Can emit additional commands.

Journal Hooks (OnXxxJournal): Execute when a journal entry is created on an actor.

See all actor lifecycle hooks →

Rule Lifecycle Hooks

These hooks fire when rules themselves are created, updated, or deleted — useful for syncing rule configuration to external systems or triggering downstream workflows.

OnRuleCreated

Fires after a rule has been created. Receives the new rule's full state.

Supported effects: messageActor, scheduleJob, sendEmail

→ Runtime reference

OnRuleUpdated

Fires after a rule has been updated. Receives both the new state (rule) and the previous state (before), making it easy to detect what changed.

Supported effects: messageActor, scheduleJob, sendEmail

→ Runtime reference

OnRuleDeleted

Fires after a rule has been deleted. Receives the rule's final state before deletion.

Supported effects: messageActor, scheduleJob, sendEmail

→ Runtime reference

Choosing the Right Hook

Use Actor Before Hooks when:

• Validating input before operations complete
• Preventing invalid state changes
• Checking business rule constraints

Use Actor After Hooks when:

• Sending notifications
• Triggering external integrations
• Creating related entities
• Scheduling follow-up work

Use Actor Command Hooks when:

• Deriving additional changes from commands
• Applying cascading updates
• Enforcing command combinations

Use Rule Lifecycle Hooks when:

• Auditing rule changes in an external system
• Invalidating caches when rule configuration changes
• Triggering workflows that depend on which rules are active

See Also

• Rules Overview — Introduction to rules
• Actor Lifecycle Hooks — Full actor hook reference
• Rule Effects — Available effects
• Common Patterns — Recipe-style examples
• Runtime Reference — Detailed hook documentation