Lifecycle hooks

Register a handler

Subscribe during your plugin's register(ctx) call:

ctx.hooks.on('order.paid', async (event) => {
  ctx.logger.info('Order payment received', {
    orderId: event.orderId,
    amountCents: event.amountCents,
  })
})

Order events

channelId and channel can be null for legacy or channel-less orders. Monetary amounts are integer cents.

The hooks above are emitted at specific lifecycle points in the kernel. They are not a change feed for every direct database update or every administrative mutation.

Execution behavior

Handlers for an event run concurrently. The bus waits for them, catches individual failures, and logs the failing plugin. One failing handler does not prevent the other handlers from running.

The hook bus is in-process and does not itself provide durable delivery or automatic retries. For slow external work, use the available job infrastructure and design the operation to tolerate repeated execution.

Plugin isolation and cleanup

Each subscription is associated with the package name. Unloading a plugin detaches that package's event handlers. Do not register handlers repeatedly from a timer or request callback.

Plugins execute in the kernel process. When reading or writing shop data, preserve the relevant tenant and channel context; the fact that an event contains an order ID does not make unrelated shop data part of that event.

HTTP delivery

If your integration runs outside the kernel, checkout webhooks provide signed HTTP delivery. They are separate from this hook bus and have different payloads and delivery semantics.