概要

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の設定はチームの管理者のみ設定メニューに表示されます。

リクエスト

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

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

Payload

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

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

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

Item、User型がどのようなプロパティを含むかは、公式ドキュメントの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で作成します。

その結果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プロパティがcreated、modelがitemであることから記事の新規作成であることがわかります。

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

応用例

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

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

概要