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.completedandpayrun.acceptedto 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
nameandat; 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.