# 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](https://code.salaxy.com/white-label/how-it-works.md).

*Diagram: The 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. (Purple: Salaxy. Grey: your page. The message goes one way, from the iframe to your page.)*

## 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](https://test-embed.palkkaus.fi/iframe-tester.html), 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](https://code.salaxy.com/get-started/environments.md) 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](https://code.salaxy.com/white-label/how-it-works.md).
- **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](https://code.salaxy.com/white-label/navigation.md)), 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](https://code.salaxy.com/security/impersonation.md)), then reload the iframe with the token in the URL hash. The URL is described in [URL parameters and sizing](https://code.salaxy.com/white-label/url-parameters.md).

## 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.
