How to create new tickets in Freshservice using Webhooks – Datadog

This guide shows you how to use our Webhooks integration to open new tickets in Freshservice when a monitor alerts.

Setup

To begin, open the Webhooks integration tile, go to the Configuration tab, then scroll to the bottom form to add a new Webhook.

Name

Provide your webhook with a name. This name will be mentioned in your monitor using @webhook-[name]. For example, if you name your webhook freshservice, you can open a ticket from your monitor by mentioning @webhook-freshservice in the monitor message.

URL

Freshservice has 2 different versions of their API. In this guide we will be using V2, but it is possible to use V1 with slight modifications to your JSON payload.

In the URL field enter the following endpoint:

https://[your domain].freshservice.com/api/v2/tickets

Your Name and URL settings should look like the following:

Custom Payload

First, ensure Use custom payload is checked so the JSON payload you enter in the Custom Payload section is used. If you don’t do this, the standard Datadog payload will be sent to Freshservice, resulting in a failed request.

Next, you will need to enter a new ticket JSON payload. The following example uses only the required fields, so please review Freshservice’s Ticket endpoint documentation for more options on how to customize your payload:

{
"email":"[email address to associate with ticket]",
"subject":"$EVENT_TITLE",
"description":"<img src=\"$SNAPSHOT\" /><hr/>$TEXT_ONLY_MSG",
"status":2,
"priority":2
}

There are a few things to note here:

Values such as $EVENT_TITLE are variables used by our webhook integration. For a full list of these variables and their meaning, refer to the webhook integration tile or our webhook integration documentation.
Manually enter an email address for the email field instead of using the variable of $EMAIL, which is only populated when mentioning the webhook in an Event Stream comment and not used within Monitor Alerts.
The description field of the payload accepts HTML. Our $EVENT_MSG variable renders your monitor’s message in Markdown, which is not supported by Freshservice’s API, so $TEXT_ONLY_MSG is used in this example instead, along with a graph snapshot.
The status and priority fields are numbers mapped to different values. To see these values, visit Freshservice’s documentation linked above.

Authentication

Freshservice’s API uses Basic Access Authentication. You will need to send your Base64 encoded credentials in the Authorization request header. Accepted credentials are your username and password in username:password format, or your API key, available on the right hand side of your Profile Settings within Freshservice.

To set this up in your webhook, add the following to your Headers section:

{"Authorization":"Basic [Base64 encoded credentials]"}

Finishing Up

Be sure to click Install Integration (or Update Configuration if you have previously entered another webhook definition) to save your changes!

Usage

You can now add the @webhooks-freshservice (or the name you defined earlier) at-mention to your monitor message, and the webhook will be triggered when the monitor changes state.

We recommend adding your at-mention inside of the {{#is_alert}} or {{#is_warning}} conditionals. If not, a new ticket will be created when the monitor recovers, as the webhook will be triggered again. For example:

{{#is_alert}}
    {{host.name}} is down!
    @webhook-freshservice
{{/is_alert}}

After your monitor triggers, your new ticket will appear in your Freshservice dashboard:

Caveats

Ticket Creation

Using the Webhooks integration will only create tickets. Updating an existing ticket requires a PUT method, and at the time of writing our Webhooks integration only supports POST methods.

Status and Priority

Our $ALERT_STATUS and $PRIORITY variables return strings (such as “ALERT” and “NORMAL”) instead of a numerical value expected by Freshservice’s API. To setup different levels of status and priorities, create duplicate webhooks with different names and different hard-coded status and priority fields. Then at-mention those webhooks inside of related conditional statements, for example:

{{#is_warning}}
    Disk space usage is above 80%
    @webhook-freshservice-warning
{{/is_warning}}
{{#is_alert}}
    Disk space usage is above 95%
    @webhook-freshservice-alert
{{/is_alert}}

Tagging

Tagging is supported in Freshservice’s API, but note the following:

The tags parameter in your JSON payload must be an array, not a list of strings. That means that you cannot use our $TAGS webhook variable, as it returns a comma separated list of tags associated with the monitor.
Tags added to your JSON payload must not contain a : character, so you may not be able to map all of your Datadog tags to Freshservice. If a : character exists in your tags, your request will fail.
Please review our Webhook integration documentation for more variables that may be useful for Freshservice tags. In the following example, $HOSTNAME and $ORG_ID are used:

{
"email":"[email address to associate with ticket]",
"subject":"$EVENT_TITLE",
"description":"<img src=\"$SNAPSHOT\" /><hr/>$TEXT_ONLY_MSG",
"status":2,
"priority":2,
"tags":["$HOSTNAME", "$ORG_ID"]
}

Troubleshooting

If your webhooks fail to send after your monitor triggers, go to your Event Stream and search for sources:webhooks status:error. This will show you events for why your webhooks have failed, which should contain troubleshooting information: