Events in the page

Every component reports what happens to your page through one event bus, in both shells. Use the events for analytics, for marking a user's progress in your own UI, or to refresh your own data. They are not a delivery mechanism for your systems: for that, use Webhooks.

<PayrooProvider adapter={adapter} onEvent={(e) => track(e.name, e.payload)}>
PayrooEmbed.mount({ /* … */ onEvent: (name, payload) => track(name, payload) });

An event is { name, payload, at, shell } with shell react or frame. Payloads carry identifiers and state only: employerId, resource { type, id, revision? }, sometimes state or stepId. A payload can never carry a value: the runtime refuses to emit one that contains amounts, account numbers or tax file numbers.

Business events

Event When
company.created a company was provisioned through the page (the showcase's walkthrough)
company.onboarding.step_completed a Company setup step became complete; stepId names it
company.onboarding.completed every setup step is complete
company.ready_for_payroll readiness turned true
employee.created, employee.updated an employee was saved
employee.invited an invitation was issued
employee.onboarding.step_completed, employee.onboarding.completed self-onboarding progress and completion
payrun.created, payrun.updated, payrun.line_updated a pay run was created or a line edited
payrun.approved, payrun.reopened approval and its reversal
payrun.lodging lodgement handed to the channel
payrun.accepted, payrun.rejected the ATO's outcome
payslip.available, payment_file.available a document can be opened
document.opened a document link was minted
session.expired the session ended and the runtime is asking your session route for a new one

payrun.lodged is declared for completeness and never emitted by the embedded path.

Shell events

frame.ready, frame.mounted, frame.resize, frame.blocked, frame.error describe the Payroo frame's life (useful for layout and for diagnosing a Content-Security-Policy that blocks it); securefield.changed, securefield.handle, securefield.blur come from secure fields and carry validity, never the value; session.expiring fires before session.expired so you can refresh early.

Patterns

  • Journey marking. Watch company.ready_for_payroll, employee.onboarding.completed and payrun.accepted to light up your own checklist.
  • Refresh your cache. On payrun.* reload what your backend holds about the company's payroll state, or let the webhook do it server-side.
  • Analytics. Send name and at; the payload's ids are stable and safe to store.

What you should see

In the showcase, the Events page prints every event of the session as it happens; the same stream reaches your onEvent in the native shell and crosses the frame boundary in the frame shell with identical names and payloads.