Tickets Freshservice avec des webhooks

Ce guide vous explique comment utiliser l’intégration Webhooks Datadog pour ouvrir de nouveaux tickets dans Freshservice lorsqu’un monitor envoie une alerte.

Implémentation

Pour commencer, ouvrez le carré d’intégration Webhooks, accédez à l’onglet Configuration, puis faites défiler la page vers le bas pour ajouter un nouveau webhook.

Nom

Donnez un nom à votre webhook. Ce nom est utilisé dans le message de votre monitor (consultez la section Utilisation) avec @webhook-<NOM>. Par exemple, si vous nommez votre webhook freshservice, vous pouvez ouvrir un ticket à partir de votre monitor en mentionnant @webhook-freshservice dans le message du monitor.

URL

L’API Freshservice se décline en deux versions différentes. Ce guide utilise la V2, mais il est possible d’utiliser la V1 en apportant quelques modifications à votre charge utile JSON.

Dans le champ URL, entrez l’endpoint suivant :

https://<VOTRE_DOMAINE>.freshservice.com/api/v2/tickets

Charge utile

Saisissez une nouvelle charge utile de ticket au format JSON. L’exemple suivant utilise uniquement les champs obligatoires. Consultez l’endpoint de ticket de Freshservice pour découvrir d’autres options de personnalisation de votre charge utile :

{
  "email": "[adresse e-mail à associer au ticket]",
  "subject": "$EVENT_TITLE",
  "description": "<img src=\"$SNAPSHOT\" /><hr/>$TEXT_ONLY_MSG",
  "status": 2,
  "priority": 2
}

Remarques :

  • Les valeurs telles que $EVENT_TITLE sont des variables utilisées par l’intégration Webhooks. Pour obtenir la liste complète de ces variables ainsi que leur signification, consultez le carré d’intégration Webhooks ou la documentation sur l’intégration Webhooks.
  • Saisissez manuellement une adresse e-mail dans le champ d’e-mail au lieu d’utiliser la variable $EMAIL : cette dernière est uniquement renseignée lorsque le webhook est mentionné dans un commentaire du flux d’événements et ne peut pas être utilisée dans les alertes de monitor.
  • Le champ description de la charge utile prend en charge le code HTML. La variable $EVENT_MSG génère le message de votre monitor au format Markdown, qui n’est pas pris en charge par l’API de Freshservice. Utilisez donc $TEXT_ONLY_MSG à la place, avec un snapshot de graphique.
  • Les champs status et priority sont des nombres mappés à différentes valeurs. Pour afficher ces valeurs, consultez l’endpoint de ticket de Freshservice.

Authentification

L’API de Freshservice utilise l’authentification basique. Vos identifiants chiffrés en Base64 doivent être envoyés dans l’en-tête de requête Authorization. Sont acceptés comme identifiants votre nom d’utilisateur et votre mot de passe au format nomutilisateur:motdepasse, ou votre clé d’API Freshservice.

Pour configurer l’authentification dans votre webhook, ajoutez la ligne suivante à votre section Headers :

{"Authorization": "Basic <IDENTIFIANTS_ENCODÉS_BASE64>"}

Pour terminer

Dans le carré d’intégration Webhooks, cliquez sur Install Integration ou Update Configuration (si vous avez déjà ajouté une définition de webhook) pour enregistrer vos modifications.

Utilisation

Ajoutez @webhook-<NOM> au message de votre monitor. Le webhook se déclenche lorsque le monitor change d’état.

Il est recommandé d’ajouter votre @mention à l’intérieur de l’expression conditionnelle {{#is_alert}} ou {{#is_warning}}. Exemple :

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

Lorsque votre monitor déclenche une alerte, un nouveau ticket s’affiche dans votre dashboard Freshservice. Si vous avez choisi de ne pas utiliser d’expression conditionnelle, un ticket est créé lorsque le monitor repasse à son état normal au prochain déclenchement du webhook.

Limites

Création de tickets

L’intégration Webhooks peut uniquement créer des tickets. La mise à jour d’un ticket existant requiert une méthode PUT, et l’intégration Webhooks prend uniquement en charge les méthodes POST.

État et priorité

Les variables $ALERT_STATUS et $PRIORITY renvoient des chaînes (comme ALERT et NORMAL) plutôt qu’une valeur numérique, tel qu’attendu par l’API de Freshservice. Pour configurer différents états et niveaux de priorité, dupliquez des webhooks avec les champs d’état et de priorité codés en dur. Mentionnez ensuite ces webhooks à l’intérieur d’une expression conditionnelle. Exemple :

{{#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

Le tagging est pris en charge dans l’API de Freshservice. Veuillez toutefois noter ce qui suit :

  • Le paramètre tags de votre charge utile au format JSON doit être un tableau. Cela signifie que vous ne pouvez pas utiliser la variable de webhook $TAGS, qui renvoie une liste de chaînes séparées par des virgules.
  • Les tags ajoutés à votre charge utile JSON ne doivent pas contenir de caractère :. Il est donc possible que vous ne puissiez pas mapper tous vos tags Datadog à Freshservice. Si un caractère : existe dans vos tags, votre requête échoue.
  • Consultez la documentation sur l’intégration Webhooks pour découvrir d’autres variables pouvant être utilisées pour les tags Freshservice. Dans l’exemple suivant, les paramètres $HOSTNAME et $ORG_ID sont utilisés :
{
  "email": "<ADRESSE_EMAIL_À_ASSOCIER_AU_TICKET>",
  "subject": "$EVENT_TITLE",
  "description": "<img src=\"$SNAPSHOT\" /><hr/>$TEXT_ONLY_MSG",
  "status": 2,
  "priority": 2,
  "tags": ["$HOSTNAME", "$ORG_ID"]
}

Dépannage

Si l’envoi de votre webhook échoue après le déclenchement de votre monitor, accédez au flux d’événements et recherchez sources:webhooks status:error. Cette requête renvoie les événements associés à des webhooks ayant échoué et contenant des informations de dépannage. Exemple :

- Reply status code was: HTTP 401
- Reply content was:
  {"code":"invalid_credentials","message":"You have to be logged in to perform this action."}

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Intégration WebhooksDOCUMENTATION more more