Webhooks を使用した Freshservice チケット

To find out if this integration is available in your organization, see your Datadog Integrations page or ask your organization administrator.

To initiate an exception request to enable this integration for your organization, email support@ddog-gov.com.

このガイドでは、Datadog Webhooks インテグレーションを使用して、モニターがアラートを出すときに、Freshservice で新しいチケットを開く方法について説明します。

セットアップ

最初に Webhooks インテグレーションタイルを開き、Configuration タブに移動して画面の一番下にあるフォームまでスクロールし、新しい Webhook を追加します。

名前

Webhook に名前を付けます。この名前がモニターメッセージに @webhook-<名前> で表示されます。たとえば、Webhook に freshservice という名前を付けた場合、モニターメッセージで @webhook-freshservice をメンションすれば、モニターからチケットを開くことができます。

URL

Freshservice には 2 つのバージョンの API があります。このガイドでは V2 を使用しますが、JSON ペイロードに少し修正を加えれば、V1 を使用することもできます。

URL フィールドに、次のエンドポイントを入力します。

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

ペイロード

新しいチケットの JSON ペイロードを入力します。次の例は、必須フィールドだけを使用しています。ペイロードのカスタマイズオプションについて、詳しくは Freshservice のチケットエンドポイントを参照してください。

{
  "email": "[チケットに関連付けるメールアドレス]",
  "subject": "$EVENT_TITLE",
  "description": "<img src=\"$SNAPSHOT\" /><hr/>$TEXT_ONLY_MSG",
  "status": 2,
  "priority": 2
}

注:

  • $EVENT_TITLE などの値は、Webhook インテグレーションで使用される変数です。この変数の一覧と、それぞれの意味については、Webhook インテグレーションタイル、または Webhook インテグレーションのドキュメントを参照してください。
  • email フィールドには $EMAIL 変数を使用せず、メールアドレスを直接入力してください。この変数は、Webhook をイベントストリームでメンションする場合にのみ値が入力され、モニターアラート内では使用されません。
  • ペイロードの description フィールドは HTML を受け取ります。$EVENT_MSG 変数は、モニターのメッセージを Markdown で表示しますが、Freshservice の API には対応していないため、上記の例では $TEXT_ONLY_MSG をグラフのスナップショットと一緒に使用しています。
  • status と priority のフィールドには、さまざまな値に対応付けられた数値を指定します。これらの値については、Freshservice によるチケットエンドポイントの情報を参照してください。

認証

Freshservice の API は、Basic 認証を使用します。Base64 でエンコードされた資格情報を、Authorization リクエストヘッダーで送る必要があります。ユーザー名とパスワードを ユーザー名:パスワード の形式で入力するか、または Freshservice API のキーを、資格情報として送ることができます。

Webhook でこれを設定するには、以下を Headers セクションに追加します。

{"Authorization": "Basic <BASE64でエンコードされた資格情報>"}

最後に

Webhook インテグレーションタイルで、Install Integration または（以前に Webhook の定義を入力していれば）Update Configuration をクリックし、変更を保存します。

使用方法

@webhook-<名前> をモニターメッセージに追加します。モニターの状態が変わると Webhook がトリガーされます。

@ メンションは、以下の例のように {{#is_alert}} または {{#is_warning}} 条件の内部に追加することをお勧めします。

{{#is_alert}}
    {{host.name}} がダウンしました！
    @webhook-freshservice
{{/is_alert}}

モニターがアラートをトリガーすると、新しいチケットが Freshservice のダッシュボードに表示されます。条件付きステートメントを使用しない場合は、モニターが回復したときに Webhook がもう一度トリガーされるため、新しいチケットが作成されます。

制限

チケットの作成

Webhooks インテグレーションで可能なのはチケットの作成だけです。既存のチケットを更新するには PUT メソッドが必要ですが、Webhooks インテグレーションがサポートするのは POST メソッドだけです。

ステータスと優先度

$ALERT_STATUS と $PRIORITY の変数は、Freshservice の API が期待する数値ではなく、（ALERT や NORMAL などの）文字列を返します。さまざまなレベルのステータスやプライオリティを設定するには、重複する Webhook を作成して、ステータスとプライオリティのフィールドをハードコーディングし、それらの Webhook を関連する条件付きステートメントの内部で @-メンション してください。以下に例を示します。

{{#is_warning}}
    ディスクスペースの使用率が 80% を超えました
    @webhook-freshservice-warning
{{/is_warning}}
{{#is_alert}}
    ディスクスペースの使用率が 95% を超えました
    @webhook-freshservice-alert
{{/is_alert}}

タグ付け

タグ付けは Freshservice API でサポートされていますが、以下の点に注意してください。

  • JSON ペイロードの tags パラメーターは、配列にする必要があります。つまり、Webhook の $TAGS 変数は（コンマで区切られた文字列のリストを返すので）使用できません。
  • JSON ペイロードに追加するタグに : の文字を含めると、Datadog のすべてのタグを Freshservice に対応付けできない場合があるので避けてください。タグに : の文字が存在すると、リクエストが失敗します。
  • Freshservice のタグに使用できる変数について詳しくは、Webhook インテグレーションのドキュメントを参照してください。以下の例では、$HOSTNAME と $ORG_ID が使用されています。
{
  "email": "<チケットに関連付けるメールアドレス>",
  "subject": "$EVENT_TITLE",
  "description": "<img src=\"$SNAPSHOT\" /><hr/>$TEXT_ONLY_MSG",
  "status": 2,
  "priority": 2,
  "tags": ["$HOSTNAME", "$ORG_ID"]
}

トラブルシューティング

モニターのトリガー後に Webhook が送信に失敗する場合は、イベントストリームに移動して、sources:webhooks status:error を探してください。Webhooks が失敗したイベントを探し、そこに含まれる情報（以下の例を参照）をトラブルシューティングに使用することができます。

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

その他の参考資料

お役に立つドキュメント、リンクや記事:

Webhooks インテグレーションDOCUMENTATION more more