Table of contents
HaloPSA Setup
This guide walks through connecting HaloPSA to WorkSights. Unlike most integrations, there is no OAuth redirect - you create an API Application inside your own HaloPSA tenant and paste the credentials into WorkSights, then configure a webhook in your own tenant so ticket events reach WorkSights. The process takes longer than most WorkSights integrations and involves a few steps on the Halo side.
HaloPSA and HaloITSM both use the same API. Self-hosted Halo instances are also supported.
Connecting HaloPSA
Step 1: Create an API Application in HaloPSA
In your HaloPSA tenant, navigate to Configuration → Integrations → API. Create a new API Application with the following settings:
- Authentication Method: Client ID and Secret (Services)
- Login Type: Agent
- Agent to log in as: Application Identity
- Identity Role: sys-all-permissions
Note: “Administrator” as the Identity Role will not work. Sys-all-permissions is required.
Once the application is created, click the Permissions tab and tick each of the following scopes individually. Scopes are not granted automatically. Even with sys-all-permissions selected, the application has no access until each scope is manually checked:
read:ticketsread:customersread:assetsread:contractsread:projectsread:kbadmin:webhooks
Save the application. Copy the Client ID and Client Secret - you will need these in the next step.
Step 2: Connect in WorkSights
In WorkSights, go to Settings → Services and select HaloPSA. Enter the following:
- Tenant URL: Your HaloPSA tenant address (e.g., yourcompany.halopsa.com). For HaloITSM tenants, use your haloitsm.com address. For self-hosted instances, use your custom hostname.
- Client ID: From the API Application you created in Step 1.
- Client Secret: From the API Application you created in Step 1.
WorkSights validates your credentials and establishes the connection. This step alone does not yet bring any ticket events through — that requires Step 3 below.
Step 3: Configure the Webhook in Your Halo Tenant
Unlike most WorkSights integrations, the webhook that delivers ticket events is not registered automatically. You need to create it yourself in your Halo tenant:
- In your HaloPSA tenant, go to Configuration → Integrations → Webhooks and create a new webhook.
- Point it at the webhook URL WorkSights shows you on the HaloPSA connection page. This is currently a direct WorkSights processing URL rather than a worksights.ai-branded address — that is expected.
- If you set a signing secret on the webhook in Halo, paste the same secret into the Webhook secret field on the WorkSights connection page so deliveries can be verified.
Ticket events will not reach WorkSights until this webhook is created and pointed at the correct URL.
Step 4: Agent Mapping
After connecting, WorkSights imports your agent list from HaloPSA and presents a mapping screen. Match each Halo agent to the corresponding WorkSights user by email where possible. WorkSights will attempt automatic matching first.
Only mapped agents will have their ticket activity attributed on the timeline. Agents who are not mapped will not generate any activity in WorkSights, regardless of their ticket volume.
What Happens Next
Once the connection is established, the webhook is configured in your Halo tenant, and agents are mapped, WorkSights begins receiving ticket events as they happen in HaloPSA: new tickets, status changes, agent updates, and user replies.
There is no backfill. Only events that occur after both the connection and the webhook are set up will appear in WorkSights. Ticket activity that predates this will not be imported.
Agent mappings can be reviewed and updated at any time from the HaloPSA integration page in Settings → Services. If new agents are added to your Halo tenant after the initial connection, use Refresh Connection to re-pull the agent list and map them.