Hooks

Hooks let implementors observe and optionally mutate customer and subscription writes, plus inbound Stripe events. Every domain mutation emits a before event and an after event.

See also: How to Extend for packaging extensions and the audit-log and payments examples.

Accessing Hooks

import { Subscrio, HookEvents } from 'core.typescript';

const subscrio = new Subscrio({
  database: { connectionString: process.env.DATABASE_URL! }
});

const hooks = subscrio.hooks;

using Subscrio.Core;
using Subscrio.Core.Application.Hooks;

var subscrio = new Subscrio(config);
var hooks = subscrio.Hooks;

Before vs After

• Handlers are awaited sequentially. The first throw stops remaining handlers for that emit.
• Payload data is loaded/built only when at least one listener is registered for that event. Multiple handlers share one payload (built once).
• Each domain event includes source: api | stripe | system.
• Each domain event includes phase: before | after.

Mutation Rules (before only)

• Handlers may mutate fields on evt.new (or evt.New in .NET).
• Subscrio applies those fields onto the domain entity before persist.
• Identity fields:
• On create, changing key via a before-hook is allowed (conflict checks re-run).
• On update, changing key via a before-hook is rejected.
• Status transitions for archive/unarchive are still driven by the service (entity methods), not by free-form status edits alone.
• after payloads clone DTOs; mutations to new are not applied.

entityId and customerId

Typical values:

• *.created.before: entityId is null (row not inserted yet).
• *.created.after: entityId is set to the new PK.
• Update / archive / delete before and after: entityId is set when the row already exists.

Throw Semantics

Event Catalog

Event names use the pattern {resource}.{action}.{before\|after}.

Customer

Subscription

Stripe Inbound

Payload Shape

Domain Mutation Payload

type HookSource = 'api' | 'stripe' | 'system';
type HookPhase = 'before' | 'after';

interface EntityMutationHookEvent<T> {
  type: string;
  phase: HookPhase;
  source: HookSource;
  occurredAt: string; // ISO
  entityId: number | null;
  customerId?: number | null; // subscription events
  old: T | null;
  /** before: mutable proposed DTO; after: immutable clone of persisted DTO */
  new: T | null;
}

interface CustomerMutationHookEvent extends EntityMutationHookEvent<CustomerDto> {}

interface SubscriptionMutationHookEvent extends EntityMutationHookEvent<SubscriptionDto> {
  featureKey?: string;
  value?: string;
  overrideType?: string;
}

public class CustomerMutationHookEvent
{
    public required string Type { get; init; }
    public required string Phase { get; init; }   // "before" | "after"
    public required string Source { get; init; }  // "api" | "stripe" | "system"
    public required string OccurredAt { get; init; }
    public long? EntityId { get; init; }
    public CustomerDto? Old { get; init; }
    public CustomerDto? New { get; set; } // mutable on before
}

public class SubscriptionMutationHookEvent
{
    public required string Type { get; init; }
    public required string Phase { get; init; }
    public required string Source { get; init; }
    public required string OccurredAt { get; init; }
    public long? EntityId { get; init; }
    public long? CustomerId { get; init; }
    public SubscriptionDto? Old { get; init; }
    public SubscriptionDto? New { get; set; }
    public string? FeatureKey { get; set; }
    public string? Value { get; set; }
    public string? OverrideType { get; set; }
}

T / DTO types are the public JSON shapes (CustomerDto / SubscriptionDto), not domain entities.

Stripe Received Payload

interface StripeReceivedHookEvent {
  type: 'stripe.received.before' | 'stripe.received.after';
  phase: 'before' | 'after';
  occurredAt: string;
  data: Stripe.Event;
}

public class StripeReceivedHookEvent
{
    public required string Type { get; init; }
    public required string Phase { get; init; }
    public required string OccurredAt { get; init; }
    public required Event Data { get; init; }
}

Registration API

Method Catalog

Config-Time Registration

import { Subscrio, HookEvents } from 'core.typescript';

const subscrio = new Subscrio({
  database: { connectionString: process.env.DATABASE_URL! },
  hooks: {
    [HookEvents.StripeReceivedBefore]: async ({ data }) => {
      await audit.logInboundStripe(data);
    },
    [HookEvents.CustomerUpdatedBefore]: async ({ old, new: next, source }) => {
      await audit.log('customer.updated.before', { old, new: next, source });
    },
    [HookEvents.CustomerCreatedAfter]: async ({ entityId, new: customer }) => {
      await notify.customerReady(entityId!, customer!);
    },
  },
});

using Subscrio.Core;
using Subscrio.Core.Application.Hooks;
using Subscrio.Core.Config;

var subscrio = new Subscrio(new SubscrioConfig
{
    Database = new DatabaseConfig { ConnectionString = conn },
    Hooks = new SubscrioHooksOptions
    {
        OnStripeReceivedBefore = async (evt, ct) =>
            await audit.LogInboundStripeAsync(evt.Data, ct),
        OnCustomerUpdatedBefore = async (evt, ct) =>
            await audit.LogAsync(evt.Type, evt.Old, evt.New, evt.Source, ct),
        OnCustomerCreatedAfter = async (evt, ct) =>
            await notify.CustomerReadyAsync(evt.EntityId!.Value, evt.New!, ct),
    }
});

Runtime Registration

const off = subscrio.hooks.on(HookEvents.SubscriptionUpdatedBefore, async (evt) => {
  await audit.logDiff(evt.old, evt.new, evt.source);
});

// later
off();

// or
subscrio.hooks.off(HookEvents.SubscriptionUpdatedBefore, handler);

var off = subscrio.Hooks.OnSubscriptionUpdatedBefore(async (evt, ct) =>
{
    await audit.LogDiffAsync(evt.Old, evt.New, evt.Source, ct);
});

// later
off();

Aborting a Mutation (before only)

subscrio.hooks.on(HookEvents.CustomerUpdatedBefore, async ({ new: next }) => {
  if (next?.email?.endsWith('@blocked.test')) {
    throw new Error('Blocked customer domain');
  }
});

subscrio.Hooks.OnCustomerUpdatedBefore(async (evt, ct) =>
{
    if (evt.New?.Email?.EndsWith("@blocked.test") == true)
    {
        throw new InvalidOperationException("Blocked customer domain");
    }
});

Mutating Proposed Data (before only)

subscrio.hooks.on(HookEvents.CustomerCreatedBefore, async (evt) => {
  evt.new!.displayName = evt.new!.displayName?.trim() ?? null;
});

subscrio.Hooks.OnCustomerCreatedBefore(async (evt, ct) =>
{
    if (evt.New != null)
    {
        evt.New.DisplayName = evt.New.DisplayName?.Trim();
    }
});

Migration from Old Event Names

Older docs and code used unsuffixed names such as customer.created and HookEvents.CustomerCreated. Those names are removed.

TypeScript: replace HookEvents.CustomerCreated with HookEvents.CustomerCreatedBefore or CustomerCreatedAfter (same pattern for every event).

.NET: replace OnCustomerCreated with OnCustomerCreatedBefore or OnCustomerCreatedAfter (same pattern for every registration method and SubscrioHooksOptions property).

Guidance:

• Validation, enrichment, and abort → *.before
• Side effects that need a committed row / entityId → *.after
• Audit that must not write if the mutation fails → prefer *.after, or accept before-hook trade-offs

Coverage

Hooks fire from:

Related Workflows

• Customer and subscription public APIs emit domain hooks around each write. See Customers and Subscriptions.
• Stripe inbound processing emits stripe.received.before, domain hooks with source: stripe, then stripe.received.after. See Stripe Integration.
• Packaging reusable handlers (audit log, etc.): How to Extend.