Appearance
Events from the embedded white label Finland
The embedded payroll UI runs in an iframe and can tell your page when something happens. It uses the browser's postMessage, so you only add a message listener to your page. Use it to know when the user is signed in and the UI is ready. For how the iframe is built and loaded, see How embedded white label works.
Events
| Message | When it is sent |
|---|---|
{ "salaxySessionEvent": "success" } | The session is set and the user is authorised. Sent each time the app sets the session. |
{ "salaxySessionEvent": "failure" } | There is no session, or the session is not authorised. For example the token is missing or invalid. |
The UI sends these messages only when it runs inside a frame. A few payment channels have an extra event built in for them; if you need an event that is not listed, ask Salaxy.
The tester lists more than the app sends
The iframe tester, Salaxy's own example page, also has branches for expired and logout. The app does not send them today, so do not rely on them. Handle failure instead.
Listen to the events
js
const iframe = document.getElementById("salaxyIframe");
const embedOrigin = "https://test-embed.palkkaus.fi"; // production: https://embed.palkkaus.fi
window.addEventListener("message", (event) => {
// Only trust messages from your own Salaxy iframe.
if (event.source !== iframe.contentWindow || event.origin !== embedOrigin) {
return;
}
switch (event.data?.salaxySessionEvent) {
case "success":
showMyMenu();
break;
case "failure":
reloadWithNewToken();
break;
}
});Examples use the test host; see Environments for demo and production.
Security
- Check the sender. The UI posts to any origin (target origin
*), so your page cannot assume a message is from Salaxy. This is general web advice, not a Salaxy rule: compareevent.sourcewithiframe.contentWindowandevent.originwith the embed host before you act. The hosts are on How embedded white label works. - No secrets in the message. It carries no token and no personal data, only the event name. Do not treat it as proof of identity; your backend still decides who the user is.
Typical use
- Show your menu after
success. If you drive the iframe from your own menu (see Navigation), show it only when the UI is signed in. Until then, show a loading indicator. - Recover on
failure. Get a new access token for the user from your backend (impersonation flow), then reload the iframe with the token in the URL hash. The URL is described in URL parameters and sizing.
Checklist
- You listen to
messageonwindowand checkevent.sourceandevent.origin. - Your page works if no event ever arrives: show a timeout message instead of waiting for ever.
failureleads to a new token and a reload, not to a retry loop without a new token.- You do not rely on
expiredorlogout. - You ignore any other message that is not listed here.

