Skip to content

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 from the iframe to your pageThe Salaxy payroll UI inside the iframe posts a message to the parent window with postMessage. Your page receives it in a message listener, checks where it came from, and then acts on it, for example by showing your own menu.Salaxy iframesession ready or failedpostMessage{ salaxySessionEvent }Your pagemessage listener
Purple: Salaxy. Grey: your page. The message goes one way, from the iframe to your page.

Events ​

MessageWhen 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: compare event.source with iframe.contentWindow and event.origin with 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 message on window and check event.source and event.origin.
  • Your page works if no event ever arrives: show a timeout message instead of waiting for ever.
  • failure leads to a new token and a reload, not to a retry loop without a new token.
  • You do not rely on expired or logout.
  • You ignore any other message that is not listed here.

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.