HaloITSM Guides
Documentation to assist with the setup and configuration of the HaloITSM platform
Instant Email Processing with Azure (The Webhook Method)
This video covers the Mailbox Setup for Email Processing via Webhooks (Read the guide for full setup and how to configure error notifications per agent and common mailbox errors)
Topics Covered In This Lesson
- Enabling the Incoming Service
- Configuring the New Mailbox with the Azure Connection Type
- Creating the App Registration and Adding the Credentials to Halo
- Adding the API Permissions on Azure
- Application Access Policies (Restrict which users your Azure application can access)
- Create The Subscription
- Configuring Email/ Halo Integrator Error Notifications Per Agent
- Common Mailbox Errors
Halo has the capability to process emails via webhooks, incoming emails will be processed significantly faster (seconds instead of minutes), this can be acheived due to the changes made to emailing services. If the incoming/ outgoing service is not yet active in your instance, and you are unsure of the implications of activating it, please contact your account manager or the Halo support team. To begin configuring this service, navigate to Configuration > Advanced Settings > *Scroll to the "Backend Services" dropdown* and check on the setting "Use Incoming Service", you must also have the scheduling service enabled.
Fig 1. Enabling the Incoming Service
Next create a new mailbox in Halo (Or reconfigure your current mailbox *Recommended to do this out of hours so that nothing is affected*) by going to Configuration > Email > *Click on Mailbox Setup* > *Click on "New" (Top RHS)* :
Fig 2. Mailbox Creation Screen with the Method set to "Webhooks"
Webhooks
A webhook is sent to the Halo API when an email is received in the mailbox, providing instant delivery and processing of any emails that are received. The task scheduling service that is also used for the mailbox scan will also run to retry any potential failed webhooks, but the frequency will be decreased. This method uses application permissions in Azure and has fewer required permissions than the above method. There are additional security steps that are recommended when using this method, which are outlined in more detail later on.
Next go to the Azure Portal to configure a new app registration:
Fig 3. Navigating to Microsoft Entra
Fig 4. Clicking into the App Registration Area
Fig 5. Creating a New App Registration
For this setup of a mailbox (Using Webhooks) you do not require any Redirect URI's. Set the registration to "Single Tenant"
Fig 6. Registering Without Adding a Redirect URI
After registering, copy the Application ID and the Tenant ID over to your new mailbox on Halo, as well as the secret. To generate a secret, click into the "Certificates anf Secrets" area within your app registration. Make sure to copy the "Value" of the secret, not the Secret ID.
NB: After generating the secret, you must copy the value and store it somewhere safe on your computer, the value will only be copyable for a limited amount of time.
Fig 7. Creating a New Secret
Fig 8. Copying the Secret Value
Then go back to the mailbox creation screen on Halo and add in your credentials you have just generated:
Fig 9. The Credentials to Add in on the New Mailbox
You can now connect an email account to your mailbox *MAKE SURE THE INBOX IS EMPTY BEFORE ADDING AND CONNECTING TO THE HALO MAILBOX, IF IT IS NOT, ALL EMAILS IN THE INBOX WILL BE TURNED INTO TICKETS*.
API Permissions
First of all, remove user.read from the permissions, then add the following:
- Mail.ReadWrite
- Mail.Send
- offline_access
Each permission can be added by following these steps:
- Navigate to the API permissions tab and select Add a permission.
- Select Microsoft Graph as the API.
- Choose the type of permission depending on the method you are using. Choosing an incorrect permission type will prevent you from fully configuring the mailbox later in Halo.
- Search for the permissions, and select the necessary permissions that are required.
- Once added, grant admin consent for the tenant:
Additional restrictions (Webhooks only)
If you are using the webhooks method, it is highly recommended that you create an application access policy to restrict which users your Azure application can access. Without this, the application will be able to read, write and send emails for all users within the Azure tenant (All mailboxes).
(More details on configuring this can be found here: Limiting application permissions to specific Exchange Online mailboxes - Microsoft Graph | Microsoft Learn)
A regular background poll of the mailbox will still take place so that in the event of issues the mail is still picked up.
Create the Subscription
After adding in the credentials to the mailbox in Halo, and adding the API Permissions on Azure, you can save the mailbox page. Now you will find a new button on the mailbox page, which you can click on: "Create Subscription" (located below the app registration credentials in Halo). This will have an expiry date that will self update when close to expiry, There is no need to manually update:
After connecting the webhook mailbox, if you are deleting your old mailbox that was connected to the outgoing default, make sure to go to the "Outgoing Email Defaults" found in configuration > email, and change the default connection to the new mailbox, without doing this step, you will not see anything populate in the email from field when emailing clients.
Checkout this guide for information on mailbox from address override hierarchy: Link to Guide
Error Notifications
Send Error Notifications for emails and the Halo Integrator, to specific agents (Configuration > Teams & Agents > Agents > Click into an Agent > *Preferences Tab*):
Common Errors
The first thing to try when a mailbox stops working and no error below matches your issue, is to Disconnect and then reauthorise the mailbox in Halo
Error | Solution |
Length Cannot Be less than zero (Parameter 'length') | When this occurs, you must create a new secret and make sure to copy the "Value" when generating the secret, not the Secret ID. Make sure to store this "Value" somewhere safe as it is important and can't be copied again after you click off the app registration page. |
Error is not defined, and you are in doubt as of what to do | Disconnect and then reauthorise the mailbox in Halo if in doubt |
Failed to retrieve agents - 400 Bad Request: "Token refresh failed - invalid_grant - AADSTS9002313: Invalid request. Request is malformed or invalid. | reauthorise mailbox, if not working try regenerating the secret, make sure to copy the "Value" when generating the secret, not the Secret ID. Make sure to store this "Value" somewhere safe as it is important and can't be copied again after you click off the app registration page. |
Connection Failed for refreshing access token for mailbox ID 3 - AADSTS9002313: Invalid request. Request is malformed or invalid. | reauthorise mailbox, if not working try regenerating the secret, make sure to copy the "Value" when generating the secret, not the Secret ID. Make sure to store this "Value" somewhere safe as it is important and can't be copied again after you click off the app registration page. |
Emails not coming through to halo but mailbox is working and inbox is being emptied? | Run Report “select top 100 * from incomingemail order by IEdatecreated desc” then do a ctrl + f for rule and check to make sure it isn’t being caught by an email rule, if it is, it will be evident on the report which email rule is binning off all emails. Emails can then be added back from the deleted folder (in your outlook account) to inbox and then they will be processed back into halo once placed into the inbox folder. |
Popular Guides
- Asset Import - CSV/XLS/Spreadsheet Method
- Call Management in Halo
- Creating a New Application for API Connections
- Creating Agents and Editing Agent Details
- Departments, Teams and Roles
- Halo Integrator
- Importing Data
- Multiple New Portals with different branding for one customer [Hosted]
- NHServer Deprecation User Guide
- Organisation Basics
- Organising Teams of Agents
- Step-by-Step Configuration Walk Through
- Suppliers