2017年03月29日
コーディルテクノロジー株式会社

WebHookコネクターの使い方を教えてください。

WebHookコネクターとは、Connectと外部サービスを接続する汎用的な仕組みを提供するコネクターであり、接続先URL(エンドポイント)に対してHTTP POSTリクエストを送ることで、イベントの発生を相手先サービスへ通知することができるようにするものです。
ConnectのWebHookコネクターは、接続方向によって2種類の機能を提供します。

  • 外部サービス → Connect
  • Connect → 外部サービス

外部サービス → Connect

これは外部サービスで発生した何らかのイベントをConnectへ通知する仕組みです。

利用方法
コネクター固有のWebHook URLへPOSTリクエストを送ることでイベントを通知し、TRIGGER:when receivedメソッドで通知されたイベントを取得します。

例えば上のようなコネクターがある場合、使用例に書かれたcurlコマンドによって、コネクターへイベントを送ることができます。このコネクターのTRIGGER:when receivedメソッドは、受け取ったPOSTリクエストのペイロード内のJSON文字列を解釈し、各プロパティを出力パラメーターとして含むイベントを発します。


Connect → 外部サービス

これはConnectで発生した何らかのイベントを外部サービスへ通知する仕組みです。

利用方法
ACTION:post messageメソッドで外部サービスへイベントを通知し、外部サービスでそのイベントを取得します。

この仕組みを利用するためには、「外部サービスのWebHook URL」にJSON形式のペイロードを持つPOSTリクエストを受け入れられるURLを設定してください。

設定した外部サービスへイベントを通知するためには、ACTION:post messageを使います。このメソッドのデフォルト入力パラメーターには、texttokenがあり、それぞれの役割は次の通りです。

text 外部サービスへ送るメッセージの本文
token トークン
外部サービスへのメッセージがConnectから送られたものであることを確認するためなどの目的のために任意の文字列を指定することができます。不要な場合は指定する必要はありません。

また、デフォルト以外のパラメーターを追加することで多様なイベントを外部サービスへ通知することができます。ACTION:post messageは、トークンを含めて全てのパラメーターを次のようなメッセージとして外部サービスへPOSTします。

Content-type: application/json
{
    "text": "test message from connect",
    "token": "random string",
    "param1": "parameter1",
    "param2": 2,
    "param3": true,
    ...
}

注意: “__”で始まる名前と”perinstance”は、システムで予約されているためパラメーター名として使用できません。

外部サービスの接続検証

コネクターの接続検証を実行すると、次のようなメッセージを外部サービスへPOSTします。コネクターの使用を開始する前に、外部サービスとの接続性を確認できます。

Content-type: application/json
{
    "text": "test message from connect"
}