idobata-hooks

A collection of Idobata hooks.

How to add a new hook

First, you would create a new directory my_hook under lib/hooks. my_hook is your new hook name.

The minimal requirements are:

hook.rb: lib/hooks/my-hook/hook.rb
```
module Idobata::Hook
  class MyHook < Base
    screen_name 'My Hook'
    icon_url    'http://example.com/path/to/icon.png'
  end
end
```
- (required)
  - screen_name: The hook name. The is displayed as message sender.
  - icon_url: The icon url. The icon linked by URL is displayed as message sender.
- (optional)
templates/default.html.haml: lib/hooks/my-hook/templates/default.html.haml
```
hi from #{payload.message}.
```
You can access request body via payload in template. payload is like a struct that is automatically parsed by Content-Type.

help.html.haml: lib/hooks/my-hook/help.html.haml

%dl
  %dt Usage
  %dd
    See <a href="http://my-service.com/webhook" target="_blank">Webhook | My Service</a>.

This will be shown as an instruction for hook usage.

Customizing template

You can customize template using template_name method.

# lib/hooks/my-hook/hook.rb
module Idobata::Hook
  class MyHook < Base
    screen_name   'My Hook'
    icon_url      'http://example.com/path/to/icon.png'
    template_name { custom_template_name }

    private

    def custom_template_name
      if payload.is_urgent
        'alert.html.haml'
      else
        'default.html.haml'
      end
    end
  end
end

Treating url-encoded JSON

You can use form_json_key for payload that is posted as url-encoded JSON.

When you want to treat ⬇️,

payload={"message":"hi"}

form_json_key 'payload' is required.

# lib/hooks/my-hook/hook.rb
module Idobata::Hook
  class MyHook < Base
    screen_name   'My Hook'
    icon_url      'http://example.com/path/to/icon.png'
    form_json_key 'payload'
  end
end

Specifying content type against `Content-Type` header

You can use forced_content_type for the service that lie about content type.

# lib/hooks/my-hook/hook.rb
module Idobata::Hook
  class MyHook < Base
    screen_name         'My Hook'
    icon_url            'http://example.com/path/to/icon.png'
    forced_content_type :json
  end
end

The available values are:

:json
:xml

Ignoring request

You can use skip_processing! at before_render callback to ignore posting message.

# lib/hooks/my-hook/hook.rb
module Idobata::Hook
  class MyHook < Base
    screen_name 'My Hook'
    icon_url    'http://example.com/path/to/icon.png'

    before_render do
      skip_processing! if payload.is_bored
    end
  end
end

Unit Test

$ rake

Preview your hook

You can check a new hook on Idobata with actual HTTP request from 3rd party services.

Deploy idobata-hooks to a server which is accessible from the target service. (such as Heroku * In Heroku the environment variable BUNDLE_WITHOUT="test" is required.)
Setup idobata-hooks URL to 3rd party services.
Set generic hook URL of your room to the environment variable IDOBATA_HOOK_URL.

When idobata-hooks receive a HTTP request, it posts a new message via generic hook to Idobata.

idobata-hooks (Japanese)

hookを追加するには

まずは新しいhookのためにディレクトリを作ります。 hookの名前がmy_hookである場合、lib/hooksの下にmy-hookを作ります。

このディレクトリ配下に必要なファイルは3つです:

hook.rb
templates/default.html.haml
help.html.haml

それぞれのファイルについて説明します:arrow_down:

hook.rb

hook特有の設定を記述します。
```
module Idobata::Hook
  class MyHook < Base
    screen_name 'My Hook'
    icon_url    'http://example.com/path/to/icon.png'
  end
end
```
- (必須設定)
  - screen_name: hookの名前です。hookが作成したメッセージの発言者として表示されます
  - icon_url: hookのアイコンです。メッセージの発言者として表示されます。
- (任意設定)
templates/default.html.haml

このファイルは、リクエストからメッセージのHTMLを組み立てるためのテンプレートです。
```
hi from #{payload.message}.
```
リクエストパラメータにはpayloadメソッド経由でアクセスできます。 payloadはContent-Typeに応じて自動的にパースされたStructっぽいものです。

help.html.haml

hookの設定方法として表示されます。

%dl
  %dt Usage
  %dd
    See <a href="http://my-service.com/webhook" target="_blank">Webhook | My Service</a>.

テンプレートを使い分ける

リクエストの種類によってテンプレートを切り替えたい場合、template_nameメソッドを使うことができます。

# lib/hooks/my-hook/hook.rb
module Idobata::Hook
  class MyHook < Base
    screen_name   'My Hook'
    icon_url      'http://example.com/path/to/icon.png'
    template_name { custom_template_name }

    private

    def custom_template_name
      if payload.is_urgent
        'alert.html.haml'
      else
        'default.html.haml'
      end
    end
  end
end

この例の場合、lib/hooks/my-hook/templates/の下にalert.html.hamlとdefault.html.hamlを作成する必要があります。

urlencodedされたJSONを扱う

JSONをurlencodedした状態でリクエストを送ってくるサービスに対応するにはform_json_keyを設定します。

例えば:arrow_down:のようなリクエストを扱うためには

payload={"message":"hi"}

form_json_key 'payload'を指定します。

# lib/hooks/my-hook/hook.rb
module Idobata::Hook
  class MyHook < Base
    screen_name   'My Hook'
    icon_url      'http://example.com/path/to/icon.png'
    form_json_key 'payload'
  end
end

Content-Typeを強制する

Content-Typeを偽ってリクエストを送ってくるサービスに対応するにはforced_content_typeを設定します。

# lib/hooks/my-hook/hook.rb
module Idobata::Hook
  class MyHook < Base
    screen_name         'My Hook'
    icon_url            'http://example.com/path/to/icon.png'
    forced_content_type :json
  end
end

この設定を行うと、Content-Typeに関係なくリクエストを扱うことができます。

設定可能な値は:arrow_down:です:

:json
:xml

リクエストを無視する

リクエストの種類によってメッセージの投稿を無視したい場合、before_renderの中でskip_processing!メソッドを呼び出します。

# lib/hooks/my-hook/hook.rb
module Idobata::Hook
  class MyHook < Base
    screen_name 'My Hook'
    icon_url    'http://example.com/path/to/icon.png'

    before_render do
      skip_processing! if payload.is_bored
    end
  end
end

テスト

$ rake

フックを動作確認する

動作確認のために、実際のサービスからリクエストを受けてIdobataにメッセージを送ることができます。

idobata-hooksを外部からアクセス可能なサーバにデプロイします。 (例えばHeroku。* Heroku では環境変数BUNDLE_WITHOUT="test"を設定する必要があります。)
idobata-hooksのホスト名を環境変数IDOBATA_HOOK_HOSTに設定します。
サービスのwebhookにidobata-hooksのエンドポイントを指定します。 idobata-hooksのデプロイ先がhttp://example.comの場合はhttp://example.com/my_hookがエンドポイントです。
生成したメッセージの表示を確認するために、あなたが所属するroomのgeneric hookのURLを環境変数IDOBATA_HOOK_URLに設定してください。

この状態でidobata-hooksがサービスからのリクエストを受けると、generic hookによってIdobataにメッセージが投稿されます。

kakutani/idobata-hooks