JavaScript
Hubot
QiitaTeam

WebhookでQiita:Teamの各種イベントを受け取る

More than 1 year has passed since last update.

概要

Qiita:Teamで発生する様々なイベントはWebhookで受取ることができます。これを利用すれば新規投稿や記事の更新、コメントが投稿されたタイミングで任意の処理を実行できます。この記事はWebhookでQiita:Teamからのイベントを受け取る具体的な方法についてのメモです。

ドキュメント

Qiita:DeveloperのWebhooksにWebhookの仕様がまとまっています。ドキュメントより、Qiita:Teamから受け取れるイベントの一覧は以下のようになっています

イベント名 概要
ItemCreated 記事が作成されたときに送信
ItemDestroyed 記事が削除されたときに送信
ItemUpdated 記事が更新されたときに送信
CommentCreated コメントが作成されたときに送信
CommentDestroyed コメントが削除されたときに送信
CommentUpdated コメントが更新されたときに送信
MemberAdded チームメンバーが追加されたときに送信
MemberRemoved チームメンバーが離脱したときに送信
PingRequested Webhookの設定画面からテストを行ったときに送信
ProjectCreated プロジェクトが作成されたときに送信
ProjectDestroyed プロジェクトが削除されたときに送信
ProjectUpdated プロジェクトが更新されたときに送信

設定方法

設定メニューからWebhookの設定をします。通知したいイベントにチェックを付け保存します。URLにはイベントを送信したいURLを指定します。これで設定は完了です。Webhookの設定はチームの管理者のみ設定メニューに表示されます。

Kobito.6901by.png

リクエスト

イベントが発生すると指定したURLにPOSTリクエストが送信されます。リクエストボディにJSON形式でエンコードされた文字列が含まれ、これをPayloadと呼びます。

また、共通リクエストヘッダとしてX-Qiita-Event-ModelPayloadmodelプロパティと同様の値が、X-Qiita-TokenにWebhookに割り当てられたトークンが含まれます。

Payload

Payloadには、必ずactionプロパティとmodelプロパティが含まれ、actionプロパティは「どのイベントが発生したか」を表す文字列で、modelプロパティは「何に対してイベントが発生したか」を表す文字列です。この他に各イベントに関連するデータが含まれます。

例えば記事作成を表すItemCreatedイベントの場合、Payloadは以下の様になります。その他のイベントについては公式ドキュメントを参照してください。

プロパティ名 説明
action String "created"
model String "item"
item Item 作成された記事
user User 作成したユーザ

ItemUser型がどのようなプロパティを含むかは、公式ドキュメントのTypesから確認できます。

Webhookの受け取り

今回はHeroku上にホストしたHubotでWebhookを受け取ります。Qiita:TeamからのWebhookはPOSTリクエストですので、HubotのHTTP Listenerを利用してイベントを受け取ります。

Webhookの設定で指定するURLは/qiita/webhooksとしました。

サンプルコード

実際のコードは以下のようになります。このコードをHubotプロジェクトのscriptsディレクトリ以下に配置します。

module.exports = (robot) => {
  robot.router.post('/qiita/webhooks', (req, res) => {
    console.log(req.body);
    res.end();
  });
}

動作例

例として以下のような投稿をQiita:Teamで作成します。

Kobito.Lhacm0.png

その結果Qiita:TeamからWebhookのPOSTリクエストが送信され、以下のようなリクエストボディを受け取ることができます。

{ action: 'created',
  item: { 
    body: '<p>test</p>\n',
    coediting: false,
    comment_count: 0,
    created_at_as_seconds: 1492484003,
    created_at_in_words: '1分未満',
    created_at: '2017-04-18 11:53:23 +0900',
    id: 993851,
    lgtm_count: 0,
    raw_body: 'test\n',
    stock_count: 0,
    stock_users: [],
    tags: [],
    title: 'test',
    updated_at: '2017-04-18 11:53:23 +0900',
    updated_at_in_words: '1分未満',
    url: 'https://vasily.qiita.com/Horie1024/items/1234567890abcdefghijk',
    user:
    { id: 43438,
      profile_image_url: 'https://qiita-image-store.s3.amazonaws.com/profile-images/xxxxxx',
      url_name: 'Horie1024' 
    },
    uuid: '1234567890abcdefghijk'
  },
  model: 'item',
  user:{ 
    id: 43438,
    profile_image_url: 'https://qiita-image-store.s3.amazonaws.com/profile-images/xxxxxx',
    url_name: 'Horie1024' 
  }
}

リクエストボディのactionプロパティがcreatedmodelitemであることから記事の新規作成であることがわかります。

また、itemプロパティはItem型で表され、ドキュメントのTypes#ItemでItem型の各プロパティがどのような意味を持つのか確認できます。例えば、raw_bodyプロパティは記事本文、bodyプロパティは記事本文のHTML表現を表します。

応用例

コードからtextlintを実行すると組み合わせるとQiita:Teamに投稿されたタイミングでtextlintで文章校正を実行することが可能です。

参考