HaloITSM Guides
Documentation to assist with the setup and configuration of the HaloITSM platform
Datadog integration
In this guide we will cover:
- How to set up the Datadog integration
The Datadog integration is used to process alerts from Datadog into tickets in Halo. This allows you to monitor alerts within Halo and archive security alerts.
Connecting to Datadog
Head to configuration > integrations, here there will be a module for Datadog, enable the module by selecting the '+' icon.
Fig 1. Enable Module
Now open up the module, to connect you will need to enter the URL of your Datadog site and your API key. The site URL can be obtained from your browser when you have logged into Datadog, this will follow the format 'https://app.datadoghq.HOSTEDREGION'. Once obtained paste this into the 'Datadog Site' field in Halo.
To obtain your API key you will need to open the Datadog 'Agent Manager' application on your device. Under the 'settings' are you will see your API key, see figure 2 for reference.
Fig 2. API key in Datadog Agent Manager
Copy the API key and paste this into the 'API Key' field in Halo.
Fig 3. Fields to paste site URL and API key into
Creating an authorization application
Before we create the webhooks in Datadog, we need to create an authorization method for the webhook in Halo. Head to configuration > integrations > Halo API > view applications > new. Here, name the application something like 'Datadog authentication'. Set the Authentication Method to be 'Client ID and Secret'. Set the login type to be 'Agent' and the 'Agent to log in as' to be an agent with admin permissions. This may be an admin agent in your instance or you may have a specific API agent you would like to use.
Now head to the permissions tab, you will need to give the application the following permissions:
- all:teams
- read:tickets
- edit:tickets
Before saving, head back to the details tab and copy both the client ID and the Client secret for the application.
Fig 4. Client ID and secret for API application
Save the application, now head into Datadog.
Once in Datadog head to the 'integrations' area and open 'webhooks', if you do not have webhooks installed already you will need to install this.
Fig 5. Webhooks in Datadog
Open the webhook integration area and go to the 'Auth Methods' tab, create new Auth Method, Call this something sensible like 'Halo Authentication' and set the protocol as 'OAuth 2.0 Client Credentials'.
In the 'Access token URL field enter YOURHALODOMAIN/auth/token?tenant=TENANTNAME, your tenant name can be found by going to configuration > Halo API, here you can see your tenant name under the 'Tenant' field.
Fig 6. Tenant Name
In the 'Client ID' and 'Client Secret' fields paste the ID and secret from the application you set up in Halo.
In the 'Scope' field enter the following: 'read:tickets edit:tickets'
Save this auth method. See figure 7 for an example on how the auth method should appear.
Fig 7. Auth method in Datadog
Additional configuration for Security alerts
For security alerts only, you will need to generate an application key, this will allow you to change the status of the alert in Datadog when closing the associated ticket in Halo.
To generate an application key head to personal settings > my organisation > application keys > new key, give the key a sensible name and generate it. Copy the key from Datadog and paste it into the integration setup page in Halo. It is the key itself (not the Key ID) that you will need to copy.
Fig 8. Application Key in Datadog
Default Ticket type and End User
Before creating webhooks ensure you have set the ticket type and end user that the alerts will be logged under when they come in. If you need the ticket type/end user to vary depending on the alert this can be changed using the payload for the webhook, but these fields still need to be set. You may want to create a new ticket type for these alerts.
Creating the webhooks
There are at least two webhooks that need to be created, one to process monitoring alerts, one to process security alerts. However, you can create as many webhooks as you like, if you would like the ticket information/ticket type/user to vary depending on the alert you will need to create a different webhooks for each of these.
With the webhook integration area still open in Datadog, head to the configuration tab, create a new webhook. Call the webhook something sensible like 'Alerts-Halo'.
In the 'URL' field enter the following 'YOURHALODOMAIN/api/notify/datadog'.
In the 'Auth Method' field select the auth method we set up earlier.
To get the payload head back to Halo, configuration > integrations > Datadog > webhook, here is an example payload you can use for the webhook. This will create a ticket in Halo, populating the summary of the ticket to be the title of the event and setting the priority of the ticket to P1. This example payload can also be seen below:
{
"datadog_id": "$ID",
"security_signal_id": "$SECURITY_SIGNAL_ID",
"summary": "$EVENT_TITLE",
"priority_id": "1",
"note": "$EVENT_MSG",
"new_external_link": {
"table_id": "1",
"module_id": "391",
"third_party_id": "$ID",
"third_party_url": "$LINK",
"third_party_desc": "$SECURITY_SIGNAL_ID"}
}
Enter your payload into the payload field and save the webhook.
Fig 9. Webhook setup in Datadog
Now we can have this webhook trigger when a particular alert takes place. The setup for the webhook trigger differs slightly for monitoring and security alerts
Triggering Webhook for Monitoring alerts
To do this configure your monitoring alert in Datadog, at stage 4 'Configure notifications and automations' enter the following into the event message:
<!--StartFragment-->
@webhook-NAMEOFWEBHOOK
<!--EndFragment-->
Now save the alert. You can test the webhook using the 'Test Notifications' button on the alert page
Fig 10. Monitoring Alert setup page with webhook trigger
Once you test the notifications the tickets relating to the alert will be created in Halo almost instantly. If the test is successful, each time the alert is triggered a ticket will be created in Halo. See figure 11 to reference how the ticket will look in Halo using the example payload. Note the agent who 'opened' the ticket is the agent you set to log in as in the authentication application.
Figure 11. Ticket created from alert
Triggering Webhook for Security alerts
Open the detection rule in Datadog that is used to trigger a security alert. At stage 3 of the rule 'Set rule cases' enter '@webhook-NAMEOFWEBHOOK' into the notify field, shown in figure 12.
Fig 12. Security Alert setup page with webhook trigger
Unlike monitoring alerts, you cannot 'test' security alerts/detection rules so once you have added the webhook trigger you will need to trigger the alert to test the webhook is successful.
Once a security alert has triggered a ticket being logged in Halo, closing the ticket will change the status of the alert in Datadog to 'archived'.
How to customise the ticket created from the alert
You can adjust the example payload to control what information is pulled into the ticket in Halo, as well as change the details/ticket type/user of the ticket.
Custom Fields
To have custom fields on the ticket be populated with data from the Datadog alert, first ensure the custom fields are set against the ticket type the alert is going to create. For example, if you would like the Hostname that the alert is in regards to appear in the ticket details, create a custom field for this (it will need to be a text field) and add this to the ticket type.
Fig 13. Adding custom field to ticket type
Now the custom field is on the ticket type you can adjust the payload. Add the following into the payload:
"customfields": [
{"id": "239",
"value": "$HOSTNAME"},
]
Let's break this down. The ID we are calling on is the ID of the custom field we want to populate. You can obtain the ID by heading to configuration > custom objects > custom fields > select your custom field, once open the ID of the field will appear in the URL after 'id='
The value is the value that we would like to populate the field with. We can either assign a set value here, such as a set number/text, or use a variable to pull the data from Datadog. The variable in the above example will pull through the name of the host that triggered the alert. For a list of the variables Datadog uses see their guide here.
See below for how the payload should look once custom fields are included:
{
"datadog_id": "$ID",
"security_signal_id": "$SECURITY_SIGNAL_ID",
"summary": "$EVENT_TITLE",
"priority_id": "1",
"customfields": [
{"id": "239",
"value": "$HOSTNAME"}],
"new_external_link": {
"table_id": "1",
"module_id": "391",
"third_party_id": "$ID",
"third_party_url": "$LINK",
"third_party_desc": "$SECURITY_SIGNAL_ID"}
}
Changing ticket type/end user
To change the user that the ticket is logged under following the alert, adjust the payload for the webhook the alert is triggering. In the payload you will need to add the following:
"user_id": "X"
Where X is the id of the user that you would like the ticket to be logged under. To get the ID of a user head to the user's profile in Halo, the ID will appear in the URL following 'userid='.
To change the ticket type of the ticket that is logged following the alert, add the following to the webhook payload:
"tickettype_id": "X"
Where X is the ID of the ticket type you would like the ticket to be logged as. The ID of a ticket type can be obtained by heading to the configuration > tickets > ticket types > select the required ticket type, here the ID of the ticket type can be found in the URL following 'id='.
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