인커밍 웹훅

기술 난이도: No-code

외부 도구와 실시간으로 데이터를 주고받으세요. 웹훅은 JSON 페이로드를 담은 가벼운 HTTP POST 요청을 사용하므로 코딩이 거의 필요 없고 사실상 모든 도구·플랫폼에서 손쉽게 설정할 수 있습니다.

버튼과 메뉴를 포함한 리치 포맷의 대화형 게시물을 만들려면 Mattermost Blocks란 무엇인가요?를 참고하세요.

Mattermost에서 인커밍 웹훅을 사용하는 데는 기본적인 설정만 필요합니다. Mattermost 인터페이스에서 웹훅 URL을 생성한 뒤, 다른 서비스가 그 주소로 데이터를 보내도록 지정하면 됩니다. 이벤트를 발생시키는 외부 서비스가 웹훅이나 HTTP POST 요청으로 데이터를 보낼 수 있다면 코딩은 필요하지 않으며, 대부분의 최신 애플리케이션과 플랫폼이 이를 지원합니다. 설정은 보통 해당 서비스의 설정에 Mattermost 웹훅 URL을 붙여 넣고 어떤 유형의 이벤트를 보낼지 선택하는 것으로 끝납니다.

활용 사례 예시

Mattermost에서 인커밍 웹훅을 활용하는 몇 가지 예시입니다.

모니터링 알림

Prometheus나 Datadog 같은 모니터링 시스템의 실시간 알림을 전용 Mattermost 채널로 보내, 시스템 문제나 다운타임을 팀이 즉시 알 수 있게 합니다.

빌드 및 배포 알림

Jenkins나 GitLab CI 같은 CI/CD 파이프라인의 자동 업데이트를 채널에 게시해, 개발자가 빌드 상태·테스트 결과·배포 진행 상황을 계속 파악할 수 있게 합니다.

고객 지원 업데이트

Zendesk나 ServiceNow 같은 시스템의 신규 지원 티켓 알림을 지원 채널로 전달해, 팀이 들어오는 요청에 빠르게 대응할 수 있게 합니다.

생성

1. Mattermost에서 제품 메뉴 > 연동으로 이동합니다. 연동 항목이 보이지 않는다면 Mattermost 서버에서 인커밍 웹훅이 활성화되어 있지 않거나 관리자가 아닌 사용자에게 비활성화되어 있을 수 있습니다. 시스템 관리자는 시스템 콘솔 > 연동 > 연동 관리에서 활성화할 수 있습니다.

   

2. 연동 페이지에서 인커밍 웹훅을 선택합니다.

   

3. 인커밍 웹훅 추가를 선택합니다.

   

4. 웹훅의 이름과 설명을 입력한 뒤 채널을 선택합니다. 이 채널로 고정을 선택해 봇 게시물을 특정 채널로 제한할 수도 있고, 인커밍 웹훅 생성자가 속한 모든 공개 채널과 비공개 채널에 게시하도록 허용할 수도 있습니다. 관리자는 시스템 콘솔 > 연동 > 연동 관리에서 모든 인커밍 웹훅에 대해 채널 고정을 강제할 수 있습니다. 저장을 선택합니다.

   

5. 완료를 선택해 확인합니다. Mattermost가 고유한 웹훅 URL을 생성하며, 형태는 다음과 비슷합니다. https://your-mattermost-server.com/hooks/xxx-generatedkey-xxx. 이 URL은 비밀 정보로 취급하세요. 이 URL을 가진 사람은 누구나 여러분의 Mattermost 인스턴스에 메시지를 게시할 수 있습니다.

   

사용

메시지를 게시하려면 애플리케이션이 요청 본문에 JSON 페이로드를 담아 웹훅 URL로 HTTP POST 요청을 보내야 합니다.

curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, this is some text\nThis is more text. :tada:"}' https://your-mattermost-server.com/hooks/xxx-generatedkey-xxx

요청이 성공하면 응답 본문에 ok가 담긴 HTTP 200 응답을 받습니다.

Slack 인커밍 웹훅과의 호환성을 위해, Content-Type 헤더가 설정되어 있지 않은 경우 요청 본문 앞에 payload=를 붙여야 합니다.

게시물 예시

인커밍 웹훅으로 게시한 간단한 메시지의 예시입니다.

매개변수

JSON 페이로드에는 다음 매개변수를 담을 수 있습니다.

매개변수를 사용한 예시

{
  "channel": "town-square",
  "username": "test-automation",
  "icon_url": "https://mattermost.com/wp-content/uploads/2022/02/icon.png",
  "text": "#### Test results for July 27th, 2017\n@channel please review failed tests.\n\n| Component  | Tests Run   | Tests Failed                                   |\n|:-----------|:-----------:|:-----------------------------------------------|\n| Server     | 948         | :white_check_mark: 0                           |\n| Web Client | 123         | :warning: 2 [(see details)](https://linktologs) |\n| iOS Client | 78          | :warning: 3 [(see details)](https://linktologs) |"
}

이 페이로드는 다음과 같이 렌더링됩니다.

card prop을 사용한 예시

props 안에 card 속성을 사용하면 게시물에 정보 아이콘이 표시됩니다. 이 아이콘을 클릭하면 오른쪽 사이드바가 열리면서 해당 내용이 표시됩니다.

{
  "channel": "town-square",
  "username": "Winning-bot",
  "text": "#### We won a new deal!",
  "props": {
    "card": "Salesforce Opportunity Information:\n\n [Opportunity Name](https://salesforce.com/OPPORTUNITY_ID)\n\n-Salesperson: **Bob McKnight** \n\n Amount: **$300,020.00**"
  }
}

Slack 호환성

Mattermost는 마이그레이션을 쉽게 할 수 있도록 Slack 웹훅 형식과의 호환성을 제공합니다.

Slack 데이터 형식 변환

Mattermost는 Slack 형식의 JSON 페이로드를 자동으로 변환합니다.

• <https://mattermost.com/>는 링크로 렌더링됩니다.
• <https://mattermost.com/|Click here>는 링크가 걸린 텍스트로 렌더링됩니다.
• <userid>는 사용자 멘션을 트리거합니다.
• <!channel>, <!here>, <!all>은 채널 전체 멘션을 트리거합니다.

채널 이름을 @username으로 재정의해 다이렉트 메시지를 보낼 수도 있습니다. 예를 들어 "channel": "@jim"과 같이 지정합니다.

GitLab에서 Mattermost 웹훅 사용하기

GitLab에 내장된 Slack 연동 기능을 사용해 Mattermost로 알림을 보낼 수 있습니다.

1. GitLab에서 Settings > Services로 이동해 Slack을 선택합니다.
2. Mattermost 인커밍 웹훅 URL을 붙여 넣습니다.
3. 필요하면 Username을 설정합니다. Channel 필드는 비워 둡니다.
4. Save를 선택하고 연동을 테스트합니다.

알려진 Slack 호환성 문제

• <#CHANNEL_ID>를 사용한 채널 참조는 지원되지 않습니다.
• <!everyone>과 <!group>은 지원되지 않습니다.
• *bold* 서식은 지원되지 않습니다. 대신 **bold**를 사용하세요.
• 웹훅은 해당 웹훅을 만든 사용자에게 다이렉트 메시지를 보낼 수 없습니다.

문제 해결

인커밍 웹훅을 디버깅하려면 시스템 관리자가 시스템 콘솔 > 로깅에서 웹훅 디버깅을 활성화하고 콘솔 로그 수준을 DEBUG로 설정하면 됩니다.

자주 나타나는 오류 메시지는 다음과 같습니다.

• Couldn't find the channel: channel 매개변수에 지정한 채널이 존재하지 않습니다.
• Couldn't find the user: 지정한 사용자가 존재하지 않습니다.
• Unable to parse incoming data: JSON 페이로드의 형식이 잘못되었습니다.

연동이 렌더링된 메시지 대신 JSON 페이로드를 일반 텍스트로 게시한다면, 요청에 Content-Type: application/json 헤더가 포함되어 있는지 확인하세요.

인커밍 웹훅 더 활용하기

웹훅 메시지에 버튼, 메뉴를 비롯한 대화형 요소를 포함하면 단순한 메시지 게시를 리치하고 대화형인 알림으로 바꿔, 팀에 더 유용하고 몰입도 높은 경험을 제공할 수 있습니다.

• Mattermost Blocks: 텍스트, 이미지, 버튼, 메뉴로 구성된 구조적이고 대화형인 게시물을 만듭니다.
• Interactive Dialogs: 구조화된 입력이나 확인이 필요한 상호작용(예: "메모와 함께 확인", "사용자에게 할당")에서 사용자를 성공적인 결과로 이끕니다. 필수 필드, 최소·최대 입력 길이, 서버가 제공하는 사용자·채널 선택기, 검증된 기본값, 인라인 필드 오류, 플레이스홀더, 도움말 텍스트를 통해 사용자가 처음부터 올바른 데이터를 입력하도록 도와 데이터 품질을 높입니다.
• Message Priority: priority를 설정해 중요한 게시물을 강조하고, 필요하면 확인 응답이나 지속 알림을 요청합니다.