Custom Widgets

Accessibility: Custom Widgets are available in the Enterprise Package only.

What are Custom Widgets?

Custom Widgets cover two types of widgets you can add into your intranet:

• Embedded Widgets: These display external content inside an iframe. They’re straightforward to set up and useful when you simply want to show dashboards, tools, or web pages inside Happeo.
• Custom Apps: These go a step further, allowing deeper integrations with Happeo, such as creating fully integrated Page Widgets or Custom Search Connectors. Developers can use code templates and Happeo’s UI Kit to build them.

Together, these two options give organizations flexibility: sometimes you only need a quick embed, and other times you want a custom-built app that interacts more closely with your intranet.

Unlike the standard iFrame Widget, Custom Widgets bypass some sandboxing restrictions. This means they can display web content or applications that wouldn’t normally load in a secured iframe — opening opportunities to:

• Bring specialized tools and dashboards directly into the intranet.
• Streamline workflows by reducing the need to switch between platforms.
• Centralize external applications so employees always have a single place of truth.

⚠️ Because Custom Widgets are not sandboxed, only platform admins should create and manage them, with careful attention to security and governance.

Use cases

Custom Widgets are most valuable when your organization needs integrations or tools in Pages that are unique to your internal workflows and not available in Happeo’s App Marketplace.

Some practical examples of how organizations use Custom Widgets include:

• Internal dashboards: Embed real-time business dashboards (e.g. sales performance, project KPIs, or customer service metrics).
• Proprietary tools: Bring your organization’s own applications — such as a custom CRM, HR portal, or expense management tool — directly into Happeo so employees can access them without switching platforms.
• Custom Search Connectors: Create search integrations that pull results from your own internal knowledge bases, databases, or other systems.

By building these integrations as Custom Widgets, organizations extend their intranet beyond the standard app ecosystem and centralize access to all the digital tools employees need — whether they’re off-the-shelf Marketplace Apps or custom-built solutions.

Best practices

To get the most value from Custom Widgets while keeping your intranet secure and maintainable, consider the following best practices:

• Validate URLs and hosting environments: Always confirm that the URL of your Custom Widget works within an iframe and is served over HTTPS. Where possible, host applications on secure, reliable servers with clear access policies.
• Test before publishing: Keep apps in the In development or Testing stage until they have been fully validated. Only move them to Published once they’ve been reviewed for both functionality and security.
• Define ownership and lifecycle: Assign clear ownership for each Custom Widget. Owners should be responsible for ongoing updates, support, and removal when the widget is no longer relevant.
• Document and communicate: Document how each Custom Widget works, who manages it, and what it should be used for. Share this information on your intranet so employees know which apps are official and supported.

Create a Custom Widget

🔎 To view full technical documentation, please visit our developers page. For a light version, keep reading.

🔑 Permissions: Custom Widgets can be created only by platform admins or users with admin rights.

1. Click your avatar in the top-right corner and open the Admin Settings.
2. Then go to Apps > Custom apps.
3. Select Add custom widget. You will then be presented with two options:

Option 1: Embedded Widget

An Embedded Widget is displayed inside an iframe. This option allows you to show external content in Happeo Pages, but the content does not interact directly with Happeo itself.

When creating an embedded widget, you’ll be asked to provide:

• Widget name
• Widget URL
• Scopes (you can select multiple)
  • User ID
  • User primary email
  • User organization ID

What are scopes? – Scopes define what user-related information can be passed into the iframe when the widget loads. They are essentially permissions that allow the external content to “know” something about the person viewing it.

What is the “Secret?”

The Secret is a private key generated by Happeo. It’s used to encode the JWT (JSON Web Token) that Happeo injects into the iframe name tag whenever the Embedded Widget runs. That JWT contains the scopes (permissions) you requested, along with user and organization identifiers. Your app can then use the Secret to verify the integrity of the JWT and confirm that the request truly comes from Happeo (not a malicious actor).

• Expiry: The JWT has a 1-hour lifetime. After that, clients should expect to receive/refresh a new token; expired tokens will fail verification.
• Rotation: Treat the Secret like a password. Rotate it periodically (and immediately if you suspect exposure). When you rotate, update your server-side verification to use the new Secret; previously issued JWTs will fail once verification switches.
• Storage: Never expose the Secret in client-side code, repositories, or logs. Keep it in a secure server-side store and log verification failures for monitoring.

🔎 Read more in our developers page: Building a Custom Embedded Widget.

Ensuring the URL works

The ability of your chosen URL to display depends on the server hosting the domain. Some domains have security restrictions in place that may prevent them from loading inside an iframe.

To check if your URL will work as a Custom Widget:

1. Open this testing tool.
2. Replace the default content with the following snippet:
   1. <iframe src="https://www.[your-url]"></iframe>
3. Click Run in the top-left menu.

• If the URL appears in the right-hand preview, it will also work as an Embedded Widget in Happeo.
• If the preview is blank, the URL will not load in Happeo.

Formatting the URL correctly

• Always include https:// before the domain. For example:
  • Correct: https://hs.fi or https://www.hs.fi
  • Incorrect: hs.fi or www.hs.fi
• If the URL is misspelled or formatted incorrectly, Happeo will flag the error in the preview.

Finalizing your widget

Once you’ve entered all required fields, click Add widget. You’ll be redirected back to the Custom Apps panel in the Admin Settings, where you’ll see a confirmation of your new embedded widget.

Option 2: Custom App

A Custom App extends Happeo’s functionality by allowing deeper integration, such as creating fully integrated Page Widgets or custom Search Connectors.

You will need to provide:

1. Widget name.
2. Target section.
   1. Pages – Page widgets.
   2. Search – Search Connectors/Apps.
3. Slug (the portal to rendering inside Happeo; required for initialization of the component).

4. Code from your computer.
   • 💡 To help you get started, Happeo provides prebuilt templates in React, VanillaJS, and Lit. These templates offer a quick foundation so developers don’t have to start from scratch. Browse our Custom Widget templates.
5. (Optional): Setup URL.

What is a Setup URL? 

• The Setup URL is displayed only to admins who are configuring the app.
• When opened, Happeo automatically appends a JWT token (as a URL parameter called token).
• That token allows your app to recognize which user and which organization is opening the setup page.
• This means the Setup URL can be used to guide the admin through additional configuration steps for the app (for example: connecting an external service, choosing data sources, or setting permissions).

The Setup URL is valuable because it gives organizations a controlled way to integrate external systems. Instead of pushing configuration into the code itself, admins can manage and update integrations dynamically through this dedicated endpoint — making the intranet both extensible and easier to maintain securely.

💡 For a consistent look and feel, developers can also use Happeo’s UI Kit, which provides ready-made design components so that Custom Apps visually match the rest of your intranet.

Finalizing your app

Once you’ve entered all required fields, click Add widget. You’ll be redirected back to the Custom Apps panel in the Admin Settings, where you’ll see a confirmation of your new Custom App.

Manage Custom Widgets

⚠️ Important: New Custom Widgets automatically start in Development mode, where only admins can see them. To make them available more broadly, move them to Testing or Published once you’ve validated functionality and security.

Once you’ve created Custom Apps or Embedded Widgets, you can manage them from the Custom Apps panel. The panel provides key details for each app, including:

• Widget name.
• Status.
• Widget URL.
• Scope.
• Date modified.

When you open a specific app, you’ll have several management options:

• Share: Control who can access the app. You can share it with your entire organization or restrict it to specific users and groups. This ensures that the right tools are available to the right people, without cluttering the intranet for those who don’t need them.
• Permissions: Assign roles such as Developer, Tester, Viewer, or No permissions.
• App Progress: Define the stage of the app — In development, Testing, Published, or Unpublished. This staging process supports good governance practices by ensuring only validated apps are widely used, while experimental apps remain safely in testing.
• Edit: Update the widget’s details as needed. Remember to click Save changes at the bottom to apply your updates.
• Delete: Remove the app.

FAQ

General usage

How do Custom Widgets differ from Marketplace Apps?

Custom Widgets and Marketplace Apps share the same underlying concept. The difference lies in availability:

• Marketplace Apps are available publicly for installation.
• Custom Widgets are built for and restricted to your Happeo environment only.

Can I use Custom Widgets on mobile?

Yes. In the Happeo mobile app, Pages (including Custom Widgets) render in a webview much like on desktop, scaled for smaller screens..

Where can I find technical documentation?

You can find the full technical documentation here.

Security & governance

Can Custom Widgets access all intranet data?

No. Custom Widgets can only access the user information that you explicitly allow via scopes. They do not automatically gain access to Happeo content, posts, or files.

Functionality & limitations

Can Custom Widgets trigger actions inside Happeo (e.g. update a page)?

Partly. Developers can use the widget-sdk to perform specific, scoped actions within the widget’s context using the current user’s permissions. 

🔎 Read more in our Widget SDK: API requests page. 

Can I reuse the same Custom Widget across multiple pages?

Yes. Once a Custom Widget is created, it can be added to any Page just like other widgets.

Is there a limit to how many Custom Widgets I can create?

There is no hard technical limit within Happeo, but best practice is to keep the number manageable and relevant to avoid cluttering your Admin panel and intranet.

What happens if I disable or delete a Custom App or Embedded Widget that’s already added to a page?

If a Custom Widget is disabled or deleted, its preview within the page will show an error placeholder. Page editors can then remove the widget if they wish.

Maintenance & troubleshooting

What should I do if a Custom Widget stops working?

First, check if the external application or URL is down or has changed. If the app is still online, verify that the URL formatting, scopes, and Secret are still valid.

Can I update a Custom Widget without removing it from all pages?

Yes. Editing a Custom Widget in Admin Settings will update it everywhere it is used.