[Mattermost Integrations] Outgoing WebHook 基本編

Mattermost 記事まとめ: https://blog.kaakaa.dev/tags/mattermost/

本記事について

Mattermost の統合機能アドベントカレンダーの第 4 日目の記事です。

本記事では、Mattermost から外部アプリケーションへ投稿内容を送信できる Outgoing WebHook（外向きのウェブフック）について紹介します。

Outgoing WebHook 概要

Outgoing WebHook は、Mattermost に投稿が作成された時にその投稿情報を外部アプリケーションへ送信するための機能です。

Outgoing WebHook を使うことで、Mattermost で発生した投稿イベントを外部アプリケーションに通知することができます。

Outgoing WebHook に関する公式ドキュメントは下記になります。

• https://docs.mattermost.com/developer/webhooks-outgoing.html
• https://developers.mattermost.com/integrate/outgoing-webhooks/

一つ目の公式ドキュメントは Outgoing WebHook の概要について記述しており、二つ目の Developer Document にはより細かい開発者向けの情報が書かれています。

設定

Outgoing WebHook を利用するには、システムコンソール > 統合機能管理 > 外向きのウェブフックを有効にする の設定が有効になっている必要があります。

また、統合機能はデフォルトではシステム管理者とチーム管理者しか作成することができませんが、誰でも作成できるようにしたい場合、システムコンソール > 統合機能管理 > 統合機能の管理を管理者のみに制限するの設定を無効してください。

作成

メインメニュー > 統合機能から統合機能の画面を開き、

外向きのウェブフック > 外向きのウェブフックを追加するから、新たな Outgoing WebHook を追加します。

ウェブフックの作成画面で入力する情報は下記の通りです。

• タイトル: ウェブフックの一覧ページに表示されるタイトルです
• 説明: ウェブフックの説明です
• コンテントタイプ: 外部アプリケーションに送信するデータの形式をapplication/x-www-form-urlencoded と application/json から選択できます
• チャンネル: ここで指定したチャンネルに投稿が作成されると、外部アプリケーションへのリクエストが送信されます。トリガーワードを指定した場合、チャンネルの指定は必須ではなくなります。非公開チャンネルやダイレクトメッセージチャンネルは指定できません。
• トリガーワード: ここで指定したキーワードで始まる投稿が外部アプリケーションへ送信されます。チャンネルとトリガーワードを両方指定した場合、指定したチャンネル内のトリガーワードで始まる投稿のみが外部アプリケーションに送信されます。
• トリガーとなる条件: トリガーワードと一致する条件を指定します。スペース区切りで最初の単語がトリガーワードと完全に一致するか、トリガーワードで始まるかを設定するものであるため、日本語の投稿を対象とする場合、最初の単語がトリガーワードで始まるに設定しておくと良いかと思います。
• コールバック URL: リクエスト送信先の URL です。

Outgoing WebHook の作成が完了すると、トークンが表示されます。このトークンは、外部アプリケーションに対して送信されるリクエストに含まれる値であり、リクエストが Mattermost から送信されたことを検証するために使われます。

実行

Outgoing WebHook を実行する前に、リクエスト送信先サーバーを立ち上げておく必要があります。 今回は、送信されたリクエストの JSON ボディをログ出力する簡単なサーバーを立ち上げておきます。

package main

import (
	"encoding/json"
	"io/ioutil"
	"log"
	"net/http"

	"github.com/mattermost/mattermost-server/v5/model"
)

func main() {
	http.HandleFunc("/outgoing", func(w http.ResponseWriter, r *http.Request) {
		defer r.Body.Close()
		b, _ := ioutil.ReadAll(r.Body)
		// (1) `model.OutgoingWebhookPayload`によるリクエストの読み出し
		var payload model.OutgoingWebhookPayload
		json.Unmarshal(b, &payload)

    	log.Printf("Request: %#v", payload)
  })

	http.ListenAndServe(":8080", nil)
}

(1) Outgoing WebHook により送信される JSON データは、Mattermost 本体の model.OutgoingWebhookPayload の形式で送信されるため、この構造体を利用してデータを変換しています。

上記コードをmain.goとして保存し、go run mainを実行してサーバーを立ち上げます。Mattermost サーバーと Outgoing WebHook リクエスト受付用のサーバを同じマシン上で起動し、Outgoing WebHook 作成時のコールバック URLにlocalhostのサーバーを指定している場合、システムコンソール > 開発者 > 信頼されていない内部接続を許可するにlocalhostを追加しておく必要があります。

上記の設定が完了した後、Outgoing WebHook 作成時にチャンネルに指定したチャンネルに投稿を作成すると、

Outgoing WebHook がサーバに送信され、下記のようなリクエストの情報がコンソールに出力されます。

$ go run main.go
2020/11/03 00:10:30 Request: model.OutgoingWebhookPayload{Token:"9mgpebi9a7bq3qjedd1kt6mwtr", TeamId:"9d1xf4gg7fnibxs8fdw6fo5fre", TeamDomain:"test", ChannelId:"9eexapjuabd89fzbwfajdqhwta", ChannelName:"outgoing-webhook", Timestamp:1604329830865, UserId:"87x93uo8pfnzdro9ktcmobpa1r", UserName:"kaakaa", PostId:"au6tf4hoebyeffiaw9h1w6rpaw", Text:"こんにちは、テスト。", TriggerWord:"こんにちは、", FileIds:""}

リクエストに含まれるトークンの値(Token:"9mgpebi9a7bq3qjedd1kt6mwtr")が Outgoing WebHook 作成時に表示されていたトークンと同じものであることがわかります。

このように、Mattermost の投稿情報を外部アプリケーションへ送信することができます。外部アプリケーション側で、送信されたリクエストに応じた処理を実装することで、Mattermost から処理を起動したりすることができます。また、ウェブフックを受け取った外部アプリケーションから、再び Mattermost へ投稿を作成したりすることもできますが、その辺りは明日の記事で紹介します。

さいごに

本日は、Outgoing WebHook の基本的な使い方について紹介しました。 明日は、Outgoing WebHook に反応して外部アプリケーションから Mattermost へ投稿を作成する方法について紹介します。