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-<NAME>과 사용량 참고)에 사용됩니다. 예를 들어 Webhook 이름을 freshwater로 지정하면 모니터 메시지에서 @webhook-freshservice를 언급해 모니터에서 티켓을 열 수 있습니다.

URL

Freshservice에는 API 버전 두 개가 있습니다. 이 가이드에서는 API V2를 설명합니다. 그러나 JSON 페이로드를 약간 수정해 V1을 사용할 수도 있습니다.

URL 필드에 다음 엔드포인트를 입력하세요.

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

페이로드

새 티켓 JSON 페이로드를 입력하세요. 다음 예시에서는 필수 필드만 사용합니다. 내 페이로드를 맞춤화할 수 있는 더 많은 옵션을 보려면 Freshservice의 티켓 엔드포인트를 확인하세요.

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

참고:

  • $EVENT_TITLE과 같은 값은 Webhook 통합에서 사용되는 변수입니다. 이 변수 전체 목록과 의미를 보려면 Webhook 통합 타이틀 또는 Webhook 통합 설명서를 참고하세요.
  • 이메일 필드에는 $EMAIL 변수를 사용하는 대신 수동으로 이메일 주소를 입력하세요. 이메일 변수의 경우 Event Stream 코멘트에서 언급할 때만 채워지고 Monitor Alerts 내에서는 사용되지 않습니다.
  • 페이로드의 description 필드에 HTML 형식을 사용할 수 있습니다. $EVENT_MSG 변수는 모니터 메시지를 마크다운으로 렌더링하며, 이는 Freshservice API에서 지원되지 않습니다. 대신 $TEXT_ONLY_MSG와 그래프 스냅샷을 사용합니다.
  • status와 priority 필드는 다른 값으로 매핑되는 수치 값입니다. 이 값을 보려면 Freshservice의 티켓 엔드포인트를 참고하세요.

인증

Freshservice API에서는 기본 액세스 인증을 사용합니다. Base64 인코딩 보안 인증 정보가 Authorization 요청 헤더에 전송됩니다. username:password 형식의 사용자 이름과 암호 또는 Freshservice API 키가 허용되는 보안 인증 정보입니다.

Webhook에 이를 설정하려면 내 Headers 섹션에 다음을 추가하세요.

{"Authorization": "Basic <BASE64_ENCODED_CREDENTIALS>"}

마무리

Webhook 통합 타이틀에서 Install Integration 또는 Update Configuration(이전에 Webhook 정의를 입력한 경우)을 클릭해 변경 사항을 저장하세요.

사용법

모니터 메시지에 @webhook-<NAME>를 추가하세요. 모니터 상태가 변할 때 Webhook이 트리거됩니다.

{{#is_alert}} 또는 {{#is_warning}} 조건부 내에 @-mention을 추가하는 것이 좋습니다. 다음 예를 참고하세요.

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

모니터에서 알림을 트리거하면 Freshservice 대시보드에 새 티켓이 나타납니다. 조건부 문을 사용하지 않으면 Webhook이 다시 트리거되기 때문에 모니터가 복구될 때 새 티켓이 또 생성됩니다.

한계

티켓 생성

Webhooks 통합에서는 티켓 생성만 가능합니다. 기존 티켓을 업데이트하는 데에는 PUT 메서드가 필요한데 Webhooks 통합에서는 POST 메서드만 지원됩니다.

상태 및 우선 순위

$ALERT_STATUS와 $PRIORITY 변수에서는 Freshservice API에서 읽기 가능한 수치 값이 아닌 문자열을 반환합니다(예: ALERT 및 NORMAL). 따라서 서로 다른 상태 및 우선 순위를 설정하려면 하드 코딩된 상태와 우선 순위 필드를 지정한 Webhooks 중복 파일을 생성해야 합니다. 그리고 관련 조건부 문 내에서 이 Webhooks를 @-mention하세요. 다음 예를 참고하세요.

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

태깅

Freshservice API에서는 태깅을 지원합니다. 그러나 다음 사항에 유의하세요.

  • JSON 페이로드에 있는 태그 파라미터가 어레이여야 합니다. 따라서 $TAGS Webhook 변수의 경우 쉼표로 구분된 문자열 목록을 반환하기 때문에 사용할 수 없습니다.
  • JSON 페이로드에 추가된 태그에는 : 문자가 포함될 수 없습니다. 따라서 Datadog 태그 모두를 Freshservice에 매핑하지 못할 수 있습니다. 태그에 : 문자가 있으면 요청이 실패합니다.
  • Freshservice 태그에 유용한 변수를 더 보려면 Webhook 통합 설명서를 검토하세요. 다음 예시에서는 $HOSTNAME과 $ORG_ID가 사용되었습니다.
{
  "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"]
}

트러블슈팅

모니터가 트리거된 후 Webhooks 전송에 실패한 경우 Event Stream으로 이동해 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 통합설명서 more more