# Hoko Help

User-facing help pages for account setup, workspaces, links, analytics, billing, security, API keys, webhooks, and logs.

Full help context: https://help.hoko.to/llms-full.txt

## Help Navigation

### Help

- [Hoko CLI](https://help.hoko.to/cli)
  Install the Hoko CLI, sign in with OAuth, use API keys in automation, and fix common terminal errors.
- [Getting started](https://help.hoko.to/getting-started)
  Create a Hoko account, set up a workspace and collection, and publish your first tracked short link.
- [Profile](https://help.hoko.to/profile)
  Manage your Hoko profile details, email, localization, and account settings from one place.
- [Workspaces](https://help.hoko.to/workspaces)
  Create, switch, rename, transfer, and manage Hoko workspaces while understanding ownership limits.
- [Collections](https://help.hoko.to/collections)
  Organize campaign links into Hoko collections and manage collection-level access and lifecycle.
- [Links](https://help.hoko.to/links)
  Create and manage Hoko short links with slugs, UTM values, QR codes, previews, and eligible link controls.
- [Tags](https://help.hoko.to/tags)
  Create and apply Hoko tags to keep links searchable, filterable, and consistent across campaigns.
- [Partners](https://help.hoko.to/partners)
  Create partner records, associate partners with tracked links, and review partner campaign context.
- [UTM templates](https://help.hoko.to/utm-templates)
  Save reusable Hoko UTM templates for consistent campaign source, medium, name, term, and content values.
- [Analytics](https://help.hoko.to/analytics)
  Review Hoko clicks, recorded leads and sales, referrers, UTM values, devices, locations, tags, and CSV exports.
- [Participants](https://help.hoko.to/participants)
  Invite participants and manage workspace and collection roles, removal, and team-seat limits.
- [Access and permissions](https://help.hoko.to/access)
  Understand workspace and collection roles, feature permissions, and how to change member access.
- [API keys](https://help.hoko.to/api-keys)
  Create scoped Hoko API keys, choose permissions, rotate credentials, and keep server integrations secure.
- [Webhooks](https://help.hoko.to/webhooks)
  Set up signed workspace webhooks, understand manager access, verify receivers, and inspect delivery results.
- [Logs](https://help.hoko.to/logs)
  Browse workspace activity, filter by resource and action, and understand log access, privacy, and delivery states.
- [Billing](https://help.hoko.to/billing)
  Understand Hoko plans, subscription changes, billing status, usage limits, and account billing workflows.
- [Storage](https://help.hoko.to/storage)
  Manage files stored in Hoko, understand upload limits, and troubleshoot storage access and cleanup.
- [Security](https://help.hoko.to/security)
  Protect your Hoko account, API keys, workspace access, and sensitive link workflows with practical controls.


## Full Help Documentation

### Hoko CLI

Install the Hoko CLI, sign in with OAuth, use API keys in automation, and fix common terminal errors.

Canonical URL: https://help.hoko.to/cli

# Hoko CLI

Use Hoko from your terminal when you need repeatable link and workspace operations.

## Install

Open [cli.hoko.to](https://cli.hoko.to). The installer detects macOS, Linux, or Windows and selects the matching CPU architecture.

```bash
curl -fsSL https://cli.hoko.to/install.sh | bash
```

For PowerShell:

```powershell
irm https://cli.hoko.to/install.ps1 | iex
```

The installer detects your platform, downloads a release archive, verifies its SHA-256 checksum, installs a bundled binary, and adds the user install directory to your shell profile. Bun is not required. Open a new terminal after installation.

## Sign in or use an API key

Find the workspace ID in [workspace settings](https://dash.hoko.to/settings/workspace), then run `hoko auth login --workspace-id <workspace_id>` for a human account. The browser opens the Hoko OAuth consent page, then the CLI stores the credential in your operating system credential store.

Use `HOKO_API_KEY` for CI and server jobs:

```bash
HOKO_API_KEY=hk_... hoko links list
```

Run `hoko auth status` to see which credential is available. Run `hoko workspace select <workspace_id>` to switch workspace after login.

## Common commands

```bash
hoko links list
hoko links create --body '{"destination":"https://example.com"}'
hoko analytics list --take 50
hoko webhooks list
```

Commands return JSON. A successful command exits with `0`. Invalid input exits with `2`. A missing credential exits with `3`.

## Fix common errors

### No credential

Run `hoko auth login --workspace-id <workspace_id>` or set `HOKO_API_KEY` in the process environment. Do not paste a key into a shell history that another user can read.

### Wrong workspace

Run `hoko workspace select <workspace_id>`, then run the command again.

### Staging or local development

Pass the API and OAuth origins together:

```bash
hoko --api https://api.staging.hoko.to --issuer https://auth.staging.hoko.to auth login --workspace-id <workspace_id>
```

For local Portless development, use HTTP loopback origins:

```bash
hoko --api http://api.hoko.localhost:1355 --issuer http://auth.hoko.localhost:1355 auth login --workspace-id <workspace_id>
```

### Rate limit

Wait for the `Retry-After` value, then retry a read. Check whether a write completed before retrying it so you do not create duplicate records.

## Read the full reference

See the [CLI documentation](https://docs.hoko.to/cli) for install and command reference. The CLI host also provides [README.md](https://cli.hoko.to/README.md), a [short machine-readable guide](https://cli.hoko.to/llms.txt), and the [full machine-readable guide](https://cli.hoko.to/llms-full.txt).

---

### Getting started

Create a Hoko account, set up a workspace and collection, and publish your first tracked short link.

Canonical URL: https://help.hoko.to/getting-started

# Getting started

## Getting started overview

This overview helps you reach your first tracked link quickly.

### What you will set up

- Sign in to your account.
- Use the default workspace or create a new one.
- Create a collection for your first campaign.
- Create a link and share it.
- Open Analytics to confirm clicks.

### Recommended order

1. Review your profile name and avatar.
2. Rename the workspace if needed.
3. Create a collection for the project.
4. Create a link with a destination.
5. Check Analytics after sharing.

> [!INFO] Access is collection-based. If you cannot see a collection, ask an owner for access.

## Create an account

Create an account to access your dashboard and workspaces.

### Where to find it

- Homepage → Sign up

### Steps

1. Open the sign up page.
2. Enter your email address.
3. Enter the one-time code sent to your email.
4. Complete account setup to reach the dashboard.

### Notes

- Use an email address that you can access. Hoko sends sign-in codes to this address.
- Your first workspace is created automatically on the first sign-in.

> [!INFO] If you already have an account, use Sign in.

## Sign in

Sign in to access your workspaces and collections.

### Where to find it

- Homepage → Sign in

### Steps

1. Open the sign in page.
2. Enter your email address.
3. Enter the one-time code sent to your email.
4. Arrive at your dashboard.

### Notes

- The last used workspace is selected automatically.
- You can switch workspaces from the switcher later.

> [!INFO] Request a new one-time code if the previous code expires.

## Sign out

Sign out to end your current session.

### Where to find it

- Account menu in the dashboard header

### Steps

1. Open the account menu.
2. Select Sign out.
3. Confirm when prompted.

### Notes

- Signing out clears session cookies on this device.
- You will need to sign in again to access the dashboard.

> [!INFO] Signing out does not delete your data.

## First workspace created automatically

If you sign in for the first time and you do not have any workspaces, Hoko creates one for you.

### What is created

- A workspace named Default Workspace.
- A default collection named Links.
- You are assigned the owner role.

### What to do next

1. Rename the workspace to match your project.
2. Create additional collections as needed.
3. Update your profile and workspace images.

> [!INFO] This happens only when no workspaces exist on your account.

## Workspace switching behavior

Switching workspaces changes which collections and links you can access.

### How switching works

- Use the workspace switcher in the dashboard header.
- The selection is stored in cookies.
- If the current collection is not available, the default collection is selected.

### What changes

- Visible links and collections.
- Analytics scope.
- Default collection in forms.

> [!INFO] If you lose access to a collection, another accessible collection is selected automatically.

## Role model explained

Workspace and collection roles control different parts of your access.

### Roles

- Owner: full workspace access, including billing and ownership transfer.
- Workspace Admin: manage workspace operations and integrations, except billing and ownership.
- Collection Admin: manage assigned collections and their member roles.
- Editor: create and edit links in assigned collections.
- Viewer: read assigned collection data.
- No access: no collection role is assigned.

### Scope

Collection roles are assigned separately for each collection. You can be a Viewer in one and an Editor in another. See [Access and permissions](https://help.hoko.to/access) for the full role matrix.

> [!INFO] Owners and Workspace Admins can change workspace settings. Billing and ownership remain Owner-only.

## Troubleshooting

Use these checks when the dashboard does not load or access is missing.

### Missing dashboard access

- Sign in again to refresh your session.
- Verify you are a member of a workspace.
- Ask an owner to send a new invite.

### Workspace not found

- Open the workspace switcher and choose another workspace.
- Clear cookies and sign in again.
- Contact a workspace owner to confirm membership.

### Session expired

- Reload the page.
- Sign in again if needed.

---

### Profile

Manage your Hoko profile details, email, localization, and account settings from one place.

Canonical URL: https://help.hoko.to/profile

# Profile

## Update profile name

Update the name shown in menus, invites, and activity.

### Where to find it

- Dashboard → Settings → Profile

### Steps

1. Open Profile settings.
2. Edit your profile name.
3. Save the changes.

### Notes

- Profile names must be 3–32 characters.
- Names must be unique.

> [!INFO] Your email address does not change.

## Update profile avatar

Upload a new avatar image for your profile.

### Where to find it

- Dashboard → Settings → Profile

### Steps

1. Open Profile settings.
2. Choose a new image file.
3. Wait for the upload to finish.
4. Save the changes.

### Notes

- PNG, JPG, or SVG files only.
- Maximum size is 2 MB.
- The image is stored as a hashed file name.

> [!INFO] If no avatar is set, initials are shown instead.

## Profile image rules

Profile images follow these rules to keep storage consistent.

### Rules

- Allowed types: PNG, JPG, or SVG.
- Maximum file size is 2 MB.
- File name uses a SHA256 hash and is stored as hash.png.
- Storage path is avatar/{profileId}/hash.png.
- The database stores only hash.png.

### Tips

- Use a square image for best results.
- Keep the file size small for faster upload.

> [!INFO] The server builds the full image URL and sends it to the client.

## Troubleshooting

Use these fixes when profile updates fail.

### Failed to update profile name

- Check the 3–32 character length.
- Ensure the name is unique.
- Try saving again.

### Failed to update profile avatar

- Confirm the file type is PNG, JPG, or SVG.
- Keep the file under 2 MB.
- Retry the upload.

### Invalid image type

- Choose a PNG, JPG, or SVG file.
- Avoid unsupported formats like GIF.

### Image size exceeds limit

- Compress or resize the image.
- Upload again after reducing size.

---

### Workspaces

Create, switch, rename, transfer, and manage Hoko workspaces while understanding ownership limits.

Canonical URL: https://help.hoko.to/workspaces

# Workspaces

## Create a workspace

Create a workspace to organize a new team or project.

### Where to find it

- Workspace switcher in the dashboard header

### Steps

1. Open the workspace switcher.
2. Select Create a new workspace.
3. Enter a workspace name.
4. Confirm to create the workspace.

### Notes

- A default collection named Links is created automatically.
- You become the owner of the new workspace.
- The new workspace becomes active right away.

> [!WARNING] Creation is blocked if you reach the ownership limit.

## Workspace name rules

Workspace names keep your switcher readable and organized.

### Rules

- Name is required.
- Maximum length is 32 characters.

### Examples

- Marketing
- Client A
- Product Team

### Tips

- Keep names short for easier switching.

## Workspace slug rules

Workspace slugs appear in URLs and must be unique.

### Rules

- Slug is required.
- Length must be between 3 and 32 characters.
- Slug must be unique across workspaces.

### Tips

- Use lowercase letters, numbers, and hyphens for clarity.

## Update workspace name

Update the workspace name to keep it recognizable in the switcher.

### Where to find it

- Dashboard → Settings → Workspace

### Steps

1. Open Workspace settings.
2. Edit the workspace name.
3. Save the changes.

### Notes

- Maximum length is 32 characters.

## Update workspace slug

Update the workspace slug to change its URL identifier.

### Where to find it

- Dashboard → Settings → Workspace

### Steps

1. Open Workspace settings.
2. Edit the workspace slug.
3. Save the changes.

### Notes

- Slug length must be 3–32 characters.
- Slug must be unique.

## Update workspace image

Upload a new image to represent the workspace.

### Where to find it

- Dashboard → Settings → Workspace

### Steps

1. Open Workspace settings.
2. Choose a new image file.
3. Wait for the upload to finish.
4. Save the changes.

### Notes

- PNG, JPG, or SVG files only.
- Maximum size is 2 MB.
- The image is stored as a hashed file name.

## Workspace image rules

Workspace images follow these rules to keep storage consistent.

### Rules

- Allowed types: PNG, JPG, or SVG.
- Maximum file size is 2 MB.
- File name uses a SHA256 hash and is stored as hash.png.
- Storage path is avatar/{workspaceId}/hash.png.
- The database stores only hash.png.

### Tips

- Use a square image for consistent avatars.
- Keep the file size small for faster upload.

## Workspace ownership limits

Workspaces have ownership limits to keep accounts manageable.

### Default limit

- The default policy allows up to two owned workspaces per profile.

### What happens at the limit

- Creating new workspaces is blocked.
- You can still be invited to other workspaces.

> [!INFO] Transfer ownership if you need to stay within the limit.

## Troubleshooting

Use these fixes when workspace actions fail.

### Failed to create workspace

- Check the workspace name length.
- Confirm you have not reached the ownership limit.
- Try again after refreshing.

### Workspace name rejected

- Keep the name under 32 characters.
- Avoid empty names.

### Workspace slug rejected

- Use 3–32 characters.
- Pick a unique slug.

### Failed to update workspace image

- Use PNG, JPG, or SVG.
- Keep the file under 2 MB.
- Retry the upload.

---

### Collections

Organize campaign links into Hoko collections and manage collection-level access and lifecycle.

Canonical URL: https://help.hoko.to/collections

# Collections

## Collection concept

A collection groups related links and controls access for each participant.

### Why it matters

- Organize links by campaign, client, or product.
- Control who can view or edit links.
- Scope analytics to specific collections.

### How it connects

- Every link belongs to one collection.
- Participant roles are set per collection.

> [!INFO] Collections keep access and analytics consistent across the workspace.

## Switch the current collection

Use the collection name above the Links list to choose which collection you are working in.

### Steps

1. Open Dashboard → Links.
2. Select the current collection name in the page heading.
3. Search for and choose an accessible collection.

### Notes

- The selected collection is stored in the Links URL, so refresh, browser history, and shared links keep the same context.
- The current collection controls the Links heading, records, totals, and available actions.
- Switching the current collection does not change the workspace default collection.

> [!INFO] The workspace default is a fallback preference. The current collection is the collection selected for this Links view.

## Create a collection

Create a collection to organize links in your workspace.

### Where to find it

- Dashboard → Library → Collections
- Dashboard → Links → current collection switcher

### Steps

1. Open Collections.
2. Select New collection.
3. Enter a collection name.
4. Create the collection.

From the Links switcher, enter a new unique name and select **Create**. Hoko creates the collection and opens its empty Links view immediately.

### Notes

- Names must be unique within the workspace.
- Plan limits may apply.
- If creation fails, the previous current collection remains active and the proposed name stays available for correction.
- Creating from Library or a link form does not change the current Links collection unless that flow explicitly activates it.

> [!INFO] Owners and Workspace Admins receive access to every active collection automatically.

### No collection access

If you are an ordinary workspace member with no collection assignment, Collections shows an explicit no-access state. Ask the Owner or Workspace Admin to assign you a collection role. Owners and Workspace Admins see the normal empty or onboarding state when the workspace has no collections.

## Collection name rules

Collection names keep your library organized.

### Rules

- Name is required.
- Maximum length is 32 characters.
- Names must be unique in the workspace.

### Tips

- Use descriptive names that match your campaigns.

## Rename a collection

Rename a collection to keep labels consistent.

### Where to find it

- Dashboard → Library → Collections

### Steps

1. Open Collections.
2. Select Rename on a collection card.
3. Enter the new name.
4. Save the changes.

### Notes

- Names must remain unique within the workspace.
- Links stay in the same collection.

## Set default collection

Choose which collection is selected by default.

### Where to find it

- Dashboard → Library → Collections

### Steps

1. Open Collections.
2. Click Default on the chosen collection.

### Notes

- The default button is disabled for the current default collection.
- The default is used when switching workspaces.

> [!INFO] If the default collection is removed, another collection is selected automatically.

## Remove a collection

Remove a collection and its access from the workspace.

### Where to find it

- Dashboard → Library → Collections

### Steps

1. Open Collections.
2. Select Remove on the collection card.
3. Confirm the removal.

### Notes

- Links in the collection are removed from active views.
- Members lose access to that collection.
- The last remaining collection cannot be removed.

> [!WARNING] Removal affects links, invites, and analytics for that collection.

## Troubleshooting

Use these fixes when collection actions fail.

### Failed to create collection

- Confirm you have permission to create collections.
- Check name length and uniqueness.
- Verify plan limits.

### Duplicate collection name

- Choose a different name.
- Search for existing collections with the same name.

### Failed to rename collection

- Ensure the new name is unique.
- Keep the name under 32 characters.

### Failed to set default collection

- Try selecting another collection.
- Refresh the page and retry.

### Failed to remove collection

- Make sure it is not the only collection.
- Confirm you have delete permissions.

---

### Links

Create and manage Hoko short links with slugs, UTM values, QR codes, previews, and eligible link controls.

Canonical URL: https://help.hoko.to/links

# Links

## Link concept

A link is a short URL that redirects to a destination and tracks activity.

### Why it matters

- Measure clicks, leads, and sales.
- Organize links inside collections.

### How it connects

- Each link belongs to one collection.
- Links can include tags, partners, and UTM data.
- The collection name above the list is the current Links collection; select it to switch or create and activate another collection.

> [!INFO] Switching the current Links collection does not scope the existing all-collection Analytics view.

### No collection access

If you are an ordinary workspace member with no collection assignment, Links shows an explicit no-access state instead of an empty link result. Ask the Owner or Workspace Admin to assign you a collection role before creating or viewing links. Owners and Workspace Admins see the normal empty or onboarding state when the workspace has no collections.

## Create a link

Create a new link to share and track destinations.

### Where to find it

- Dashboard → Links

### Steps

1. Open Links.
2. Select New link.
3. Enter the destination URL.
4. Choose a collection and optional settings.
5. Create the link.

### Notes

- Destination URL and collection are required.
- New-link drafts start with the current Links collection, but eligible users may choose another writable collection.
- You can add tags, partners, or UTM data later.

## Required link fields

Links require a few fields before they can be created.

### Required fields

- Destination URL
- Collection

### Optional fields

- Short ID
- Tags
- Partner
- UTM parameters
- Comments
- QR code
- Targeting
- Expiry rules

> [!INFO] If you leave the short ID empty, a random one is generated.

## Edit a link

Edit link details without losing historical analytics.

### Where to find it

- Dashboard → Links

### Steps

1. Open Links.
2. Select a link from the list.
3. Edit the fields you need.
4. Save the changes.

### Notes

- Edits apply immediately.
- Past analytics remain tied to the link.

## Remove a link

Remove a link so it no longer appears in the workspace.

### Where to find it

- Dashboard → Links

### Steps

1. Open Links.
2. Select the link to remove.
3. Confirm deletion.

### Notes

- Removed links no longer appear in lists.
- Historical analytics remain available.

## Link filters

Filters narrow the links list to what you need.

### Available filters

- Tags
- Destinations
- Sort order

### How filters combine

Multiple filters are applied together inside the current collection. Clear filters to return to that collection's full list.

## Link search behavior

Search scans key fields to help you find links fast.

### Search coverage

- Link ID
- Link name
- Description
- Short ID
- Destination URL
- Comments

### Search tips

- Use partial keywords.
- Search is case-insensitive.

## Link tags usage

Tags help categorize links and improve filtering.

### When to use tags

- Group links across collections.
- Filter analytics by campaign or topic.

### How tags are applied

Select tags when creating or editing a link. You can add or remove tags any time.

> [!INFO] Tag changes apply immediately to filters and analytics views.

## Link partners usage

Partners connect links to affiliates or collaborators.

### When to use partners

- Track partner-driven traffic.
- Attribute conversions to a partner.

### How partners are applied

Select a partner when creating or editing a link. Partners are optional.

## Link UTM templates usage

UTM templates fill tracking parameters quickly.

### When to use UTM templates

- Reuse consistent UTM values across campaigns.
- Reduce manual entry when creating links.

### How templates are applied

Select a template in the link dialog to populate UTM fields. You can edit values after applying.

## Troubleshooting

Use these fixes when link actions fail.

### Failed to create link

- Check the destination URL.
- Select an accessible collection.
- Verify permissions.

### Invalid destination URL

- Include the full URL with https://.
- Avoid spaces or unsupported characters.

### Link not found

- Clear filters and search again.
- Verify you have access to the collection.

### Failed to update link

- Check required fields.
- Retry after refreshing the page.

### Failed to delete link

- Confirm you have delete permission.
- Try again after refreshing.

### Tag assignment failed

- Check that the tag still exists.
- Try removing and re-adding the tag.

### Partner assignment failed

- Confirm the partner exists.
- Retry after refreshing.

---

### Tags

Create and apply Hoko tags to keep links searchable, filterable, and consistent across campaigns.

Canonical URL: https://help.hoko.to/tags

# Tags

## Tag concept

Tags label links so you can filter and analyze them easily.

### Why it matters

- Filter links by campaign or theme.
- Use tags to segment analytics.

### How it connects

- Tags can be applied to any link.
- Analytics filters can use tags.

## Create a tag

Create tags to organize links and analytics.

### Where to find it

- Dashboard → Library → Tags

### Steps

1. Open Tags.
2. Select New tag.
3. Enter a tag name and color.
4. Create the tag.

### Notes

- Tag names must be unique.
- If the name is empty, a short ID is generated.

## Update a tag

Update tag names or colors to keep them consistent.

### Where to find it

- Dashboard → Library → Tags

### Steps

1. Open Tags.
2. Select a tag.
3. Edit the name or color.
4. Save the changes.

### Notes

- Names must stay unique.

## Remove a tag

Remove a tag when you no longer need it.

### Where to find it

- Dashboard → Library → Tags

### Steps

1. Open Tags.
2. Select Remove on the tag.
3. Confirm deletion.

### Notes

- Removing a tag does not delete links.
- Links will simply lose that tag.

## Tag color rules

Tag colors help you recognize categories at a glance.

### Rules

- Choose from the available color palette.
- Use high-contrast colors for readability.

### Tips

- Keep a consistent color scheme across similar tags.

## Troubleshooting

Use these fixes when tag actions fail.

### Failed to create tag

- Check tag name uniqueness.
- Verify you have permission to create tags.

### Duplicate tag name

- Use a different name.
- Search existing tags first.

### Invalid tag color

- Select a color from the provided palette.

### Failed to update tag

- Ensure the new name is unique.
- Retry after refreshing.

### Failed to remove tag

- Confirm you have delete permission.
- Try again after refreshing.

---

### Partners

Create partner records, associate partners with tracked links, and review partner campaign context.

Canonical URL: https://help.hoko.to/partners

# Partners

## Partner concept

Partners represent affiliates or collaborators tied to links.

### Why it matters

- Attribute traffic to partners.
- Measure partner performance.

### How it connects

- A link can reference one partner.
- Partners are optional for links.

## Create a partner

Create a partner to track affiliate or collaborator links.

### Where to find it

- Dashboard → Partners

### Steps

1. Open Partners.
2. Select New partner.
3. Enter the partner name.
4. Save the partner.

### Notes

- Partner name is required.
- Email and phone are optional.

## Update a partner

Update partner details to keep records accurate.

### Where to find it

- Dashboard → Partners

### Steps

1. Open Partners.
2. Select a partner.
3. Edit details.
4. Save changes.

## Remove a partner

Remove a partner when it is no longer needed.

### Where to find it

- Dashboard → Partners

### Steps

1. Open Partners.
2. Select Remove on the partner.
3. Confirm deletion.

### Notes

- Removing a partner does not delete links.
- Links will lose the partner association.

## Troubleshooting

Use these fixes when partner actions fail.

### Failed to create partner

- Ensure the partner name is provided.
- Retry after refreshing.

### Failed to update partner

- Retry after refreshing.
- Check required fields.

### Failed to remove partner

- Confirm you have delete permission.
- Try again after refreshing.

---

### UTM templates

Save reusable Hoko UTM templates for consistent campaign source, medium, name, term, and content values.

Canonical URL: https://help.hoko.to/utm-templates

# UTM templates

## UTM template concept

UTM templates store reusable tracking parameters for links.

### Why it matters

- Keep campaign tracking consistent.
- Reduce manual entry when creating links.

### How it connects

- Templates can be applied in link dialogs.
- Templates do not change existing links unless applied.

## Create a UTM template

Create a template to reuse UTM parameters.

### Where to find it

- Dashboard → Library → UTM Templates

### Steps

1. Open UTM Templates.
2. Select New template.
3. Enter template name and UTM fields.
4. Save the template.

### Notes

- Template name is required and must be unique.
- Provide at least one UTM field.
- Only fill the UTM fields you need.

## Update a UTM template

Update template values to keep tracking accurate.

### Where to find it

- Dashboard → Library → UTM Templates

### Steps

1. Open UTM Templates.
2. Select a template.
3. Edit fields and save.

## Remove a UTM template

Remove a template you no longer need.

### Where to find it

- Dashboard → Library → UTM Templates

### Steps

1. Open UTM Templates.
2. Select Remove on the template.
3. Confirm deletion.

### Notes

- Removing a template does not change existing links.

## Troubleshooting

Use these fixes when template actions fail.

### Failed to create UTM template

- Check that the name is unique.
- Retry after refreshing.

### Duplicate template name

- Choose a different template name.

### Failed to update UTM template

- Retry after refreshing.
- Check required fields.

### Failed to remove UTM template

- Confirm you have delete permission.
- Try again after refreshing.

---

### Analytics

Review Hoko clicks, recorded leads and sales, referrers, UTM values, devices, locations, tags, and CSV exports.

Canonical URL: https://help.hoko.to/analytics

# Analytics

## Analytics overview

Analytics show how your links perform over time.

### What you can see

- Clicks
- Leads
- Sales
- Top referrers
- UTM breakdowns
- Tag performance

### Data window

By default analytics load the last 30 days and are limited by your plan event caps.

> [!INFO] Analytics are scoped to collections you can access.

## Analytics scope by collection

Analytics only include collections you have access to.

### Access rules

- Viewer or higher access is required to see analytics.
- Blocked or removed participants do not see analytics.
- If you are an ordinary workspace member with no collection assignment, Analytics shows an explicit no-access state explaining that a collection role is required. Owners and Workspace Admins see the normal empty state when the workspace has no collections.

## Click analytics explained

Click analytics record every visit to a link.

### Captured details

- Destination
- Referrer
- UTM parameters
- Device and browser
- Location

### How to use

- Spot top-performing campaigns.
- Understand traffic sources.

## Lead analytics explained

Lead analytics show conversions captured as leads.

### Lead events

- Recorded when a lead is tracked.
- Linked to a click and a link.

### How to use

- Measure campaign quality.
- Compare clicks to leads for conversion rate.

## Sale analytics explained

Sale analytics track revenue events tied to links.

### Sale events

- Recorded when a sale is tracked.
- Includes amount and currency when provided.

### How to use

- Measure ROI per campaign.
- Compare revenue across collections.

## Filter behavior

Analytics filters refine what data you see.

### Filter effects

- Filters apply to charts and tables.
- Multiple filters combine together.
- Clear filters to reset the view.

## Export analytics data

Export analytics to CSV for reporting.

### How export works

- Exports reflect current filters.
- Includes recent data from the analytics window.

### Tips

- Apply filters before exporting.
- Use a spreadsheet to build charts.

## Troubleshooting

Use these fixes when analytics does not load or looks incomplete.

### Missing analytics data

- Confirm you have activity in the last 30 days.
- Check collection access.

### Access denied to analytics

- Ask an owner to grant viewer access.
- Switch to a collection you can access.
- If you have no collection assignment, ask an owner or Workspace Admin to assign you a collection role.

### Export failed

- Try exporting with fewer filters.
- Reload the page and retry.

### Slow analytics load

- Apply filters to reduce data volume.
- Refresh and try again later.

---

### Participants

Invite participants and manage workspace and collection roles, removal, and team-seat limits.

Canonical URL: https://help.hoko.to/participants

# Participants

Read [Access and permissions](https://help.hoko.to/access) for the complete workspace and collection permission matrix.

## Participant roles explained

Participant roles control access per collection.

### Roles

- Owner: full access, workspace management, billing, and ownership transfer.
- Workspace Admin: manage workspace operations, integrations, and ordinary members. Cannot manage billing, ownership, or other Workspace Admins.
- Collection Admin: manage members within assigned administrator collections.
- Editor: create and edit links and content.
- Viewer: read-only access.
- No access: hidden from the member.

### Scope

Roles are assigned per collection and can differ across collections.

For Collection Admins, Participants access is available when they are a Collection Admin in any collection. Their assignment controls apply only to collections where they are an administrator and do not depend on the currently selected collection. Workspace-wide participant removal remains unavailable.

## Invite a participant

Invite a participant and choose their collection roles.

### Where to find it

- Dashboard → Settings → Participants

### Steps

1. Open Participants settings.
2. Enter the member email.
3. Assign roles for collections.
4. Send the invite.

### Notes

- Invites are scoped to collections.
- Members only see collections they are assigned to.

## Assign collection roles

Assign different roles per collection for the same member.

### Where to find it

- Dashboard → Settings → Participants

### Steps

1. Open Participants settings.
2. Select a member or invite form.
3. Choose a role for each collection.
4. Save the changes.

### Notes

- Setting a role to none hides the collection for that member.

## Resend an invite

Resend an invite if the email was missed.

### Where to find it

- Dashboard → Settings → Participants

### Steps

1. Open Participants settings.
2. Find the pending invite.
3. Select Resend invite.

### Notes

- Only pending invites can be resent.

## Revoke an invite

Revoke an invite to stop it from being accepted.

### Where to find it

- Dashboard → Settings → Participants

### Steps

1. Open Participants settings.
2. Find the pending invite.
3. Select Revoke invite.

### Notes

- Revoked invites cannot be accepted.

## Update member roles

Change a member role for one or more collections.

### Where to find it

- Dashboard → Settings → Participants

### Steps

1. Open Participants settings.
2. Select the member.
3. Adjust roles per collection.
4. Save the changes.

### Notes

- Keep at least one owner in the workspace.

## Remove a participant

Remove a participant from the workspace.

### Where to find it

- Dashboard → Settings → Participants

### Steps

1. Open Participants settings.
2. Select the member.
3. Choose Remove participant.
4. Confirm removal.

> [!WARNING] You cannot remove the last remaining owner.

Only the Owner and Workspace Admin can use this workspace-wide action. A Collection Admin must set the member's role to **None** for the assigned collection instead; Collection Admin cannot remove a person from the workspace.

## Transfer ownership

Transfer ownership with the dedicated ownership transfer action.

### Where to find it

- Dashboard → Settings → Participants

### Steps

1. Open Participants settings.
2. Select the member.
3. Choose Transfer ownership.
4. Select the target member.
5. Confirm the change.

### Notes

- Keep at least one owner at all times.

## Troubleshooting

Use these fixes when participant actions fail.

### Invite not delivered

- Check the email address.
- Ask the invitee to check spam.
- Resend the invite.

### Invite already exists

- Check pending invites.
- Revoke and resend if needed.

### Role assignment failed

- Ensure you are the Owner, Workspace Admin, or Collection Admin for the collection you are managing.
- Retry after refreshing.

### Ownership transfer blocked

- Use the dedicated ownership transfer action.
- Confirm the target member has workspace membership.

### Failed to remove participant

- Ensure you are not removing the last owner.
- Retry after refreshing.

---

### Access and permissions

Understand workspace and collection roles, feature permissions, and how to change member access.

Canonical URL: https://help.hoko.to/access

# Access and permissions

Hoko uses two permission levels: workspace authority and collection access. Your effective access is the combination of both levels.

## How access works

Your signed-in profile must belong to the active workspace. The workspace role controls workspace-wide features. Your collection role controls data inside each collection.

Workspace owners and Workspace Admins receive access to every active collection. Ordinary members see only collections where they have an assigned role.

Protected resources and changes are checked on the server. Hiding a button alone does not set a permission, and a direct URL cannot bypass a protected action.

## Access matrix

The matrix shows effective access for each role. `All` means every active collection; `Assigned` means collections with that role; `Workspace` means the whole workspace; `Self` means your own account. `Read` means view only, `Manage` means the action is allowed, and `No` means it is blocked. `Business+` and `Plan permitting` also require the stated plan allowance.

On a narrow screen, scroll each table sideways to see every role.

### Workspace and membership

| Feature | Owner | Workspace Admin | Collection Admin | Editor | Viewer | No access |
|---|---|---|---|---|---|---|
| View workspace in switcher | Workspace | Workspace | Workspace | Workspace | Workspace | Workspace |
| View workspace settings | Read | Read | No | No | No | No |
| Update workspace name | Manage | Manage | No | No | No | No |
| Update workspace slug | Manage | Manage | No | No | No | No |
| Update workspace image | Manage | Manage | No | No | No | No |
| View Participants | Workspace | Workspace | Assigned admin collections | No | No | No |
| Invite across any collection | Manage | Manage | No | No | No | No |
| View pending invitations | Workspace | Workspace | Assigned admin collections | No | No | No |
| Resend an invitation | Manage | Manage | Assigned admin collections | No | No | No |
| Revoke an invitation | Manage | Manage | Assigned admin collections | No | No | No |
| Invite a Collection Admin | Manage | Manage | No | No | No | No |
| Invite an Editor to an assigned collection | Manage | Manage | Manage | No | No | No |
| Invite a Viewer to an assigned collection | Manage | Manage | Manage | No | No | No |
| Promote Viewer to Editor | Manage | Manage | Manage | No | No | No |
| Promote Editor to Collection Admin | Manage | Manage | No | No | No | No |
| Demote Collection Admin to Editor | Manage | Manage | No | No | No | No |
| Demote Editor to Viewer | Manage | Manage | Manage | No | No | No |
| Remove a workspace member | Manage | Manage ordinary members | No | No | No | No |
| Remove a member from an assigned collection | Manage | Manage | Manage | No | No | No |
| Grant Workspace Admin | Manage | No | No | No | No | No |
| Revoke Workspace Admin | Manage | No | No | No | No | No |
| Transfer ownership | Manage | No | No | No | No | No |
| Leave the workspace | Transfer first | Yes | Yes | Yes | Yes | Yes |

### Collections and links

| Feature | Owner | Workspace Admin | Collection Admin | Editor | Viewer | No access |
|---|---|---|---|---|---|---|
| List collections | All | All | Assigned | Assigned | Assigned | No |
| View collection details | All | All | Assigned | Assigned | Assigned | No |
| Create a collection | Manage | Manage | No | No | No | No |
| Rename a collection | Manage | Manage | Assigned | No | No | No |
| Set the default collection | Manage | Manage | No | No | No | No |
| Delete a collection | Manage | Manage | No | No | No | No |
| View links | All | All | Assigned | Assigned | Assigned | No |
| Create a link | All | All | Assigned | Assigned | No | No |
| Edit link metadata | All | All | Assigned | Assigned | No | No |
| Change link destination | All | All | Assigned | Assigned | No | No |
| Change link preview | All | All | Assigned | Assigned | No | No |
| Change link targeting | All | All | Assigned | Assigned | No | No |
| Change link expiration | All | All | Assigned | Assigned | No | No |
| Change link password protection | All | All | Assigned | Assigned | No | No |
| Change link QR settings | All | All | Assigned | Assigned | No | No |
| Move a link | All | All | Assigned source and destination | Assigned source and destination | No | No |
| Delete a link | All | All | Assigned | Assigned | No | No |
| View link analytics | All | All | Assigned | Assigned | Assigned | No |

### Shared libraries and reports

| Feature | Owner | Workspace Admin | Collection Admin | Editor | Viewer | No access |
|---|---|---|---|---|---|---|
| View tags library | Read | Read | No | No | No | No |
| See shared option names on Links page | All | All | Assigned | Assigned | Assigned | No |
| Create a tag | Manage | Manage | No | No | No | No |
| Update a tag | Manage | Manage | No | No | No | No |
| Delete a tag | Manage | Manage | No | No | No | No |
| Use existing tags on assigned links | All | All | Assigned | Assigned | No | No |
| View UTM templates library | Read | Read | No | No | No | No |
| Create a UTM template | Manage | Manage | No | No | No | No |
| Update a UTM template | Manage | Manage | No | No | No | No |
| Delete a UTM template | Manage | Manage | No | No | No | No |
| View partners library | Read | Read | No | No | No | No |
| Create a partner | Manage | Manage | No | No | No | No |
| Update a partner | Manage | Manage | No | No | No | No |
| Delete a partner | Manage | Manage | No | No | No | No |
| View customers | All | All | Assigned | Assigned | Assigned | No |
| View click analytics | All | All | Assigned | Assigned | Assigned | No |
| View lead analytics | All | All | Assigned | Assigned | Assigned | No |
| View sale analytics | All | All | Assigned | Assigned | Assigned | No |
| View Events | All | All | Assigned | Assigned | Assigned | No |
| View Journeys | All | All | Assigned | Assigned | Assigned | No |

### Integrations and billing

| Feature | Owner | Workspace Admin | Collection Admin | Editor | Viewer | No access |
|---|---|---|---|---|---|---|
| View API key metadata | Read | Read | No | No | No | No |
| Create an API key | Manage | Manage | No | No | No | No |
| Rename an API key | Manage | Manage | No | No | No | No |
| Change API key scopes | Manage | Manage | No | No | No | No |
| Change API key allowed hostnames | Manage | Manage | No | No | No | No |
| Revoke an API key | Manage | Manage | No | No | No | No |
| View webhook endpoints | Read | Read | No | No | No | No |
| Create a webhook endpoint | Business+ | Business+ | No | No | No | No |
| Update a webhook destination | Manage | Manage | No | No | No | No |
| Verify a webhook | Business+ | Business+ | No | No | No | No |
| Enable a verified webhook | Business+ | Business+ | No | No | No | No |
| Disable a webhook | Manage | Manage | No | No | No | No |
| Delete a webhook | Manage | Manage | No | No | No | No |
| Send a webhook test | Business+ | Business+ | No | No | No | No |
| View webhook delivery history | Read | Read | No | No | No | No |
| View delivery attempt details | Read | Read | No | No | No | No |
| View webhook test attempts | Read | Read | No | No | No | No |
| View activity logs | Read | Read | No | No | No | No |
| Export visible logs | Plan permitting | Plan permitting | No | No | No | No |
| Resend an eligible delivery | Business+ | Business+ | No | No | No | No |
| View billing | Read | No | No | No | No | No |
| Change the subscription | Manage | No | No | No | No | No |
| Open the billing portal | Manage | No | No | No | No | No |
| View invoice details | Read | No | No | No | No | No |
| Send invoice email | Manage | No | No | No | No | No |
| View subscription usage | Workspace | Workspace | Workspace | Workspace | Workspace | Workspace |

### Personal account

| Feature | Owner | Workspace Admin | Collection Admin | Editor | Viewer | No access |
|---|---|---|---|---|---|---|
| View own profile | Self | Self | Self | Self | Self | Self |
| Update own profile | Self | Self | Self | Self | Self | Self |
| Change own language | Self | Self | Self | Self | Self | Self |
| Change own appearance | Self | Self | Self | Self | Self | Self |

The No access column describes collection access. An ordinary workspace member with no collection assignment can still see the workspace switcher and subscription usage, but Collections, Links, and Analytics show an explicit no-access state. Owners and Workspace Admins keep the normal empty or onboarding state when the workspace has no collections because they have workspace-wide collection access. Some protected pages return an access-restricted state when the member lacks workspace authority.

## Workspace roles

### Owner

The Owner has full workspace access. The Owner can:

- update workspace settings;
- create, rename, set as default, and delete collections;
- invite and remove workspace members;
- assign collection roles;
- create and manage API keys;
- create and manage webhooks;
- view logs and resend eligible webhook deliveries;
- manage billing and subscription changes;
- appoint or remove Workspace Admins; and
- transfer workspace ownership.

The Owner role cannot be removed through an ordinary member update. Use the dedicated ownership transfer action.

### Workspace Admin

Workspace Admin is a workspace-wide operational role. A Workspace Admin can:

- update workspace settings;
- create, rename, set as default, and delete collections;
- invite and remove ordinary workspace members;
- assign collection roles below Workspace Admin authority;
- create and manage API keys;
- create and manage webhooks;
- view logs and resend eligible webhook deliveries; and
- work with all active collections.

A Workspace Admin cannot manage billing, transfer ownership, appoint or remove another Workspace Admin, or change the Owner.

### Member

Member is the base workspace role. A Member has no workspace-wide management rights. Their access comes from the collection roles assigned to them.

## Collection roles

Collection roles can differ for each collection.

### Collection Admin

Collection Admin can rename collections where they are Collection Admin. They can manage members for those collections and invite or update Editors and Viewers within that scope. They cannot create or delete collections, manage workspace settings, manage API keys or webhooks, view workspace logs, manage billing, or appoint Workspace Admins.

### Editor

Editor can create, edit, move, and delete links in assigned collections. Editor can use shared tags, partners, and UTM options while editing assigned links. Editor cannot manage members, collections, API keys, webhooks, logs, or billing.

### Viewer

Viewer can read assigned collection data, links, analytics, customers, and available reports. Viewer cannot create, edit, delete, or manage access.

### No access

No access means that no collection role is assigned. The member can remain in the workspace but cannot read collection data or use collection features.

## Feature boundaries

### Workspace settings

Only the Owner and Workspace Admin can open and update workspace settings. Only the Owner can transfer ownership or manage Workspace Admin roles.

### Collections

The Owner and Workspace Admin can create, set the default, and delete collections. The Owner and Workspace Admin can rename any collection. Collection Admin can rename an assigned collection. Editor and Viewer cannot perform collection management operations.

### Members

The Owner and Workspace Admin can manage workspace membership. Collection Admin can manage collection assignments within collections where they are an administrator. A Collection Admin cannot remove a person from the entire workspace.

### Shared libraries

The Owner and Workspace Admin can manage tags, partners, and UTM templates. These libraries are workspace-wide. The Links page can show their option names to anyone with collection access, including Viewers, even when they cannot open the library management pages. Collection Admins and Editors can apply those options to links they can edit.

### Links and analytics

Collection Admin and Editor can manage links in assigned collections. Viewer has read-only access. Owner and Workspace Admin have access across active collections.

Analytics and customer views follow the same collection scope. A plan may limit a report, export, or analytics feature after the role check succeeds.

### API keys

Only the Owner and Workspace Admin can view, create, update, and revoke workspace API keys. API key scopes control what an integration can do through the API. A key does not grant access to the dashboard, webhooks, logs, or billing.

API keys belong to the workspace. Changing the creator's human role does not revoke a key. Revoke the key explicitly when its integration must stop.

Treat every key as a password. Copy its secret when it is created, store it on the server, and revoke it when it is no longer needed.

### Webhooks and logs

Only the Owner and Workspace Admin can manage workspace webhooks or open workspace logs. Webhooks require an eligible plan. Current product policy requires Business or above for webhook creation, verification, testing, and delivery.

An Owner or Workspace Admin on an eligible plan can resend a `pending`, `failed`, or **Unconfirmed** delivery from the log row's **More options** menu when the endpoint is active. Hoko waits five minutes before allowing an Unconfirmed delivery to be resent. A pending delivery uses its existing first attempt. A failed delivery or an old Unconfirmed delivery adds a new attempt. Every resend keeps the original event ID.

Delivery history remains available after an endpoint is disabled or deleted. A deleted endpoint cannot deliver or be resent.

### Billing

Only the Owner can view billing controls, start checkout, change the subscription, open the billing portal, or manage invoices. A Workspace Admin can view operational workspace data but cannot change billing.

## Plan limits

Role and plan checks both apply to protected features. A member with the required role can still see a plan restriction when the workspace plan does not include a feature.

Plan restrictions do not grant access to a different role. Upgrading a plan does not grant access to workspace settings, integrations, logs, or billing.

## No-access states

If you are an ordinary workspace member with no collection assignment, Hoko shows an explicit no-access state in Collections, Links, and Analytics and explains that a collection role is required. Owners and Workspace Admins see the normal empty or onboarding state when their workspace has no collections. If you are not a member of the workspace, Hoko does not reveal the workspace and returns a not-found response for protected resources.

After a membership is removed or blocked, subsequent protected requests fail. Refresh the page and select another collection that you can access.

## Change access

Open **Dashboard → Settings → Participants**.

The Owner can update workspace roles. The Owner and Workspace Admin can update ordinary member collection roles. Collection Admin can update roles only within collections where they have Collection Admin access.

Use the dedicated **Transfer ownership** action to move ownership. Do not try to transfer ownership by changing a collection role.

## Related help

- [Participants](https://help.hoko.to/participants) explains invitations and collection assignments.
- [Collections](https://help.hoko.to/collections) explains collection lifecycle.
- [API keys](https://help.hoko.to/api-keys) explains scopes and key handling.
- [Webhooks](https://help.hoko.to/webhooks) explains endpoint setup and delivery behavior.
- [Logs](https://help.hoko.to/logs) explains activity history and delivery attempts.
- [Billing](https://help.hoko.to/billing) explains subscription controls.

---

### API keys

Create scoped Hoko API keys, choose permissions, rotate credentials, and keep server integrations secure.

Canonical URL: https://help.hoko.to/api-keys

# API keys

## API key concept

API keys allow programmatic access to your workspace data.

### Why it matters

- Integrate with external tools.
- Control access through scopes.

### How it connects

- Each key has read and write scopes.
- Keys are tied to the workspace.
- Allowed hostnames can limit browser usage.

> [!INFO] Treat API keys like passwords.

For outbound notifications, see [Webhooks](https://help.hoko.to/webhooks). For recorded workspace activity, see [Logs](https://help.hoko.to/logs). These are separate workspace-manager dashboard features. Only the Owner and Workspace Admin can manage or view them. API key scopes do not grant dashboard access to either feature.

## Create an API key

Create a key for integrations and automation.

### Where to find it

- Dashboard → Integrations → API Keys

### Steps

1. Open API Keys.
2. Select New key.
3. Choose scopes.
4. Add allowed hostnames if needed.
5. Create and copy the key.

### Notes

- You may only see the key value once.
- Store it securely.

## API key scopes explained

Scopes control what an API key can access.

### Scope types

- Read: view data
- Write: create or update data

### Best practice

- Grant only the scopes you need.
- Use separate keys per integration.

## Allowed hostnames configuration

Limit browser usage by restricting where a key can be used.

### How it works

- Hoko checks the Origin or Referer hostname when present.
- Requests without those headers are not filtered by hostname.
- Leave the list empty to allow any hostname.

### Examples

- `example.com`
- `api.example.com`
- `*.example.com`

## Update API key settings

Adjust the name, scopes, and allowed hostnames.

### Where to find it

- Dashboard → Integrations → API Keys

### Steps

1. Open API Keys.
2. Select the key.
3. Update the fields.
4. Save changes.

## Revoke an API key

Revoke a key to stop its access immediately.

### Where to find it

- Dashboard → Integrations → API Keys

### Steps

1. Open API Keys.
2. Select the key.
3. Choose Revoke.
4. Confirm the action.

> [!WARNING] Revoking a key will break integrations using it.

## Troubleshooting

Use these fixes when API key actions fail.

### Failed to create API key

- Check required scopes.
- Retry after refreshing.

### Missing required scopes

- Select at least one scope.

### Invalid API key

- Verify you copied the full key.
- Generate a new key if needed.
- Check allowed hostnames when calling from a browser.

### Hostname blocked

- Ensure the request Origin or Referer matches an allowed hostname.
- Add the hostname to the allowlist and try again.

### API key revoked

- Create a new key and update your integration.

---

### Webhooks

Set up signed workspace webhooks, understand manager access, verify receivers, and inspect delivery results.

Canonical URL: https://help.hoko.to/webhooks

# Webhooks

## What webhooks do

Webhooks send signed HTTPS requests from Hoko to a server you control when a subscribed workspace action is recorded. Use them to notify your own integrations. [Logs](https://help.hoko.to/logs) show recorded activity even when no webhook is configured.

## Access and availability

Open Dashboard → Integrations → Webhooks. The feature must be enabled in your deployment. Access requires an active account with the Owner or Workspace Admin role. The workspace must have an active collection. Blocked or removed memberships do not qualify.

Webhooks cover the whole workspace, not just the selected collection. Business or above is required to create, verify, test, and receive webhooks. API keys do not grant access to this dashboard: there is currently no public webhook-management API.

Active webhook allowances per workspace are Business 10, Enterprise 20, and Elite 40. Free and Pro have no webhook allowance. Storage allows five additional replacement slots (15/25/45 total), including pending and disabled entries. Delete unused entries to free slots. After a downgrade, the oldest active webhooks within the new allowance remain eligible; excess configurations are preserved without delivery.

On downgrade, sending is suspended but configuration and retained history remain accessible to the Owner and Workspace Admin. You can still disable or delete webhooks. Upgrading to an eligible plan allows active webhooks to receive new events again; disabled webhooks stay off until you verify and enable them. Missed events are not replayed, and already-sent requests cannot be recalled.

## Create and verify a webhook

With data export access (Business or above), select visible webhooks and choose **Download selected**. The button shows the selection count. The JSON download includes their IDs, names, subscribed events, statuses, and creation/verification times. It excludes destinations, signing secrets, payloads, and delivery attempts. Search and filters limit which selected webhooks are included.

1. Prepare a public HTTPS receiver using the [developer guide](https://docs.hoko.to/webhooks/introduction) and its tested receiver example.
2. Select Create webhook, enter a webhook name and receiver URL, choose the events you need, and paste an existing `whsec_` signing secret or use the shuffle control to generate one. Leave the field blank and Hoko will generate one when you create the webhook.
3. Create the pending webhook. Copy its signing secret immediately and store it only in your receiver's server-side secret storage. It cannot be reopened.
4. Make the receiver verify the signature and return the exact challenge response for `endpoint.verification`, as described in the developer guide.
5. Select Verify webhook. Only a successfully verified, active webhook receives subscribed events.
6. Send a test and inspect its delivery result. A test is a real outbound request to your receiver; handle `endpoint.test` without triggering customer business actions.

If you lose the secret, create a replacement webhook. Never paste secrets into support messages, browser code, analytics, or logs.

## Events and payloads

Select events from the current resource/action catalog. Names use dots, with camelCase where a name needs multiple words: for example `link.destination.updated` and `apiKey.revoked`. Global `profile.*` activity is excluded from workspace subscriptions. Verification and test messages are operational messages, not subscription choices.

Every subscribed workspace event uses the same thin payload: `id`, `type`, `created`, and `data` containing only the affected record `id` and `workspaceId`. This includes `lead.created` and `sale.created`; fetch record details through the relevant API when available. See the [payload contract](https://docs.hoko.to/webhooks/introduction).

## Delivery results and limits

Delivery makes one immediate, best-effort attempt. Hoko does not retry automatically or guarantee ordering. A failed receiver does not undo an accepted change in Hoko. Bulk changes may exhaust the request's delivery budget and leave some deliveries pending.

Immediate delivery supports the plan’s active webhook allowance, up to 40 webhooks. Owner and Workspace Admin actions allow 10 verification attempts per hour and 30 test sends per hour. Receiver requests are limited to 64 KiB with a three-second receiver budget; database work adds time. If rate limited, wait for the indicated retry interval. Delivery history is retained for the workspace lifetime, including after a webhook is deleted. Attempts do not consume tracked-event allowance; there is no monthly delivery quota or overage billing.

Inspect results in Webhooks and related [Logs](https://help.hoko.to/logs). From a log row's **More options** menu, an Owner or Workspace Admin on an active Business or higher plan can resend a `pending`, `failed`, or **Unconfirmed** delivery. Hoko waits five minutes before allowing an Unconfirmed delivery to be resent. A pending delivery uses its existing first attempt; a failed or old Unconfirmed delivery adds a new attempt. Every send uses a new signature timestamp and keeps the original event ID. Unconfirmed means Hoko saved no terminal result, so the receiver may have received the earlier request. Your receiver must verify signatures and durably deduplicate event IDs before applying business effects.

### View delivery history

The webhook side sheet shows the receiver URL and the 10 most recent delivery attempts. Choose **See all deliveries** from the webhook row's **More options** menu or from the side sheet to open the complete history for that webhook. The dedicated delivery page loads history in pages and lets you sort and filter the attempts without loading the entire history at once.

## Disable, replace, or delete a webhook

Disabling stops new fan-out, but cannot recall a request already sent. To change the receiver URL, first disable the webhook, select **Change receiver URL**, save the new public HTTPS URL, and select **Verify webhook**. The webhook returns to pending verification while Hoko keeps its ID, delivery history, and signing secret. Hoko sends a fresh challenge to the new destination before activation. To re-enable a disabled webhook without changing its URL, select **Verify and enable**. To change the webhook name, subscribed events, or signing secret, create and verify a replacement, then disable the old webhook. If both are active, your receiver may receive the same event through both. Delete the old webhook only when you no longer need its configuration; deletion clears its destination and signing secret but keeps its delivery history.

Select **Delete webhook** when you no longer need its configuration. Deletion hides the webhook from management, preserves its name and delivery history, and erases its signing material. The workspace activity log is separate; deleting a webhook does not erase ordinary log facts. Deleted webhooks cannot deliver or be resent.

## Troubleshooting

- Missing tab or page: check the workspace, your Owner or Workspace Admin role, and whether the deployment has the feature enabled. An upgrade does not bypass these checks. If the page reports a plan suspension, Business or above is required for sending.
- Verification fails: check the signing secret, exact raw request bytes, timestamp tolerance, and exact challenge response.
- Destination rejected: use public HTTPS. Private/local addresses and redirects are not supported; never bypass receiver signature checks.
- No event arrives: check the webhook is active, the event is selected, the action happened in this workspace, and the delivery result. Old activity is not sent retroactively.

See [developer documentation](https://docs.hoko.to/webhooks/introduction) for signatures, schemas, and receiver security.

---

### Logs

Browse workspace activity, filter by resource and action, and understand log access, privacy, and delivery states.

Canonical URL: https://help.hoko.to/logs

# Logs

## What logs show

Open Dashboard → Integrations → Logs to review recorded workspace activity: what happened, which record was affected, when it happened, and who performed the action. Logs are separate from click analytics and from your receiver's server logs. They do not require a configured webhook.

## Plan history windows

Free shows 7 days, Pro 30 days, Business 90 days, Enterprise 180 days, and Elite 365 days. These are viewable activity-history windows, separate from analytics retention. Server-side filtering applies the window to every page and filter. Downgrades hide older entries without deleting them; upgrades reveal additional history only if it is still retained. Recording supported activity continues regardless of the viewing allowance. Logs do not consume tracked-click/event quota.

## Access and availability

The feature must be enabled in your deployment. You need an active account with the Owner or Workspace Admin role. There must be at least one active collection; blocked or removed memberships do not count. Selecting a collection does not narrow the log to that collection: this is workspace-wide information. Collection members and API keys cannot use this view. There is no public log-reading API or plan upgrade requirement.

## Browse and filter

1. Select the workspace you want to inspect, then open Integrations → Logs.
2. Filter by resource, such as links or webhooks, and optionally by its associated action. Selecting a different resource resets the action filter.
3. Read the newest results first. Use the older-results control when another page is available; pages contain at most 50 entries.
4. Clear filters if no matching activity appears. No results can also mean no activity has been recorded yet.

Action names use dots, for example `link.created`, `link.destination.updated`, or `webhook.disabled`. They describe recorded facts, not commands to execute.

## Fields and privacy

Each log fact stores its own ID, workspace ID, affected record ID, action, actor ID, operation ID, and occurrence time. The actor identifies a human profile or API key; a null actor means a system action. An operation ID groups related changes, including bulk actions. Treat identifiers as sensitive business data.

Logs do not store full records, before/after values, passwords, signing secrets, or arbitrary submitted form contents. They cannot reconstruct or restore a deleted record. Global account/profile activity is not exposed in this workspace view.

## Related webhook results

Where present, entries show the associated webhook name, delivery state, and result category:

- `pending`: no attempt has started. This is not a scheduled retry or a guarantee of future delivery.
- **Unconfirmed** (`unknown`): an attempt was claimed, but no terminal result is recorded. The UI never treats it as success or failure, and Hoko cannot prove whether the receiver received it.
- `succeeded`: the sender recorded a successful response, not proof that the receiver completed its business work.
- `failed`: the sender recorded a failure. Inspect the category and fix the receiver.

From a log row's **More options** menu, an Owner or Workspace Admin on an active Business or higher plan can resend a `pending`, **Unconfirmed**, or `failed` delivery. Hoko waits five minutes before allowing an Unconfirmed delivery to be resent. A pending delivery uses its existing first attempt; a failed or old Unconfirmed delivery adds a new attempt. Every send keeps the original event ID and uses a new signature timestamp. Your receiver must deduplicate the event ID because the earlier request may have reached it.

If an endpoint is `disabled`, use **Verify and enable** on the Webhooks page to send a fresh challenge to its saved receiver with its saved signing secret. A successful challenge keeps the endpoint ID and delivery history, then changes the endpoint to `active`. Delivery stays off until the challenge succeeds. Deleting an endpoint clears its receiver and signing secret, so it cannot be re-enabled.

No delivery shown does not mean the action failed. There may have been no eligible subscription or publication may have been disabled. A log can exist without any webhook delivery. Read [Webhooks](https://help.hoko.to/webhooks) for testing and troubleshooting.

## History limitations

Logs show facts actually recorded by enabled application flows. They are not a retroactive history of all existing records, a database backup, or a guarantee that every external or direct database change is captured. A failed transaction does not leave a successful-change log.

With data export access (Business or above), select visible rows and choose **Download selected**. The button shows the selection count. The JSON download contains log IDs, timestamps, actions, record IDs, actor IDs, and operation IDs from the current page only, not hidden history or delivery details. Treat downloaded identifiers as sensitive. Logs do not provide edit or delete controls. Use a delivery row's **More options** menu to resend an eligible webhook delivery. Delivery history is retained for the workspace lifetime, including after endpoint deletion. Deleted endpoints cannot deliver or be resent; workspace deletion can remove associated logs.

If access is denied, check that you are the workspace Owner or Workspace Admin and that the deployment enables logs. Buying a different plan does not bypass those checks. See the [technical log reference](https://docs.hoko.to/logs/introduction).

---

### Billing

Understand Hoko plans, subscription changes, billing status, usage limits, and account billing workflows.

Canonical URL: https://help.hoko.to/billing

# Billing

## Current plan

View your current plan and usage limits.

### Where to check

- Dashboard → Settings → Subscription

### What you will see

- Plan name
- Usage counters
- Billing status

## Usage limits explained

Usage limits define how many resources you can use per cycle.

### Typical limits

- Links
- Events
- Collections
- Tags
- Users

### Cycle reset

Usage resets every billing cycle. You can track the cycle dates in the usage panel.

## Upgrade a plan

Upgrade to increase limits and access more features.

### Where to find it

- Dashboard → Settings → Subscription

### Steps

1. Open the Subscription page.
2. Choose a higher plan.
3. Complete checkout.

## Downgrade a plan

Downgrade if you no longer need higher limits.

### Where to find it

- Dashboard → Settings → Subscription

### Steps

1. Open the Subscription page.
2. Choose a lower plan.
3. Confirm the change.

> [!WARNING] If your usage exceeds the new limits, some actions may be blocked.

## Troubleshooting

Use these fixes when billing updates fail.

### Checkout failed

- Verify payment details.
- Try again with a different card.

### Plan not updated

- Refresh the page.
- Wait a few minutes and retry.

### Limits not refreshed

- Sign out and sign in again.
- Contact support if it persists.

---

### Storage

Manage files stored in Hoko, understand upload limits, and troubleshoot storage access and cleanup.

Canonical URL: https://help.hoko.to/storage

# Storage

## Image upload flow

Images are uploaded in a secure flow that uses signed URLs.

### Upload steps

1. The client hashes the image with SHA256.
2. The server issues a signed upload URL.
3. The image is uploaded to the avatar bucket.
4. The server stores the hash file name in the database.

## Image hashing rules

Hashing ensures consistent storage and naming.

### Hash requirements

- SHA256 hash of the file contents.
- File name is hash.png.
- Bucket is avatar.

### Folder rules

- Profile images use folder {profileId}.
- Workspace images use folder {workspaceId}.

## Avatar URL behavior

Image URLs are built on the server and sent to the client.

### How URLs are built

- The database stores only hash.png.
- The server builds /storage/avatar/{folderId}/hash.png.

### Fallbacks

- If an image fails to load, initials are shown.
- If no image is set, initials are used by default.

## Troubleshooting

Use these fixes when image uploads fail.

### Failed to generate upload URL

- Retry the upload.
- Check that the file hash is valid.

### Storage resource not found

- Confirm the bucket name is avatar.
- Ensure the folder ID matches the profile or workspace ID.

### Upload rejected

- Use PNG, JPG, or SVG.
- Keep the file under 2 MB.

### Image not visible

- Refresh the page.
- Check that the image URL is reachable.

---

### Security

Protect your Hoko account, API keys, workspace access, and sensitive link workflows with practical controls.

Canonical URL: https://help.hoko.to/security

# Security

## Session lifecycle

Sessions keep you signed in across visits.

### Session behavior

- Sessions are stored in cookies.
- Tokens refresh automatically when possible.
- Signing out clears the session.

## Cookie workspace selection

Your active workspace and collection are stored in cookies.

### What is stored

- currentWorkspaceId
- currentCollectionId

### How it is used

- Restores your last selection on next visit.
- Falls back to default collection if needed.

## Access removal behavior

When access changes, subsequent protected requests use your updated permissions.

### What happens

- Collections you no longer access disappear after refresh.
- The system selects another accessible collection when one exists.
- If your workspace membership is removed, switch to another workspace you can access.

## Troubleshooting

Use these fixes when security-related access issues occur.

### Session invalid

- Sign in again.
- Clear cookies if the issue persists.

### Access revoked

- Contact a workspace owner to restore access.
- Check your invite status.

### Workspace not accessible

- Switch to another workspace.
- Sign out and back in.

---