Webhook

Webhookを利用すると、Qiita Teamで発生する様々なイベントを外部のサービスと連携できます。Qiita Teamで記事が作成されたり、記事にコメントが付けられたりすると、設定されたURLに対してHTTP経由でPOSTリクエストが送信されます。

設定方法

自分の所属しているチームにWebhookを設定するには、チーム設定画面からWebhooksの画面に遷移し、設定を行います。1つのチームで複数のURLを設定でき、それぞれのURLに対して受信するイベントの種類を指定できます。なお、Webhookの設定を変更できるのはチームの管理者のみとなります。

リクエスト

Webhookの機能から送られるすべてのHTTPリクエストはPOSTリクエストで送信されます。リクエストボディにはJSON形式でエンコードされた文字列(以下これをPayloadと呼びます)が含まれます。共通のリクエストヘッダとして、X-Qiita-Event-Model にPayloadのmodelプロパティと同様の値が含まれます。また、Qiita Teamから送信されたリクエストであることを保証するため、X-Qiita-Token にWebhookに割り当てられたトークンが与えられます。トークンはチーム設定画面から確認できます。

Payload

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

ItemCreated

記事が作成されたときに送信されます。

Payload

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

Example

request-body-example
{
  "action": "created",
  "item": {
    "body": "<p>test</p>\n",
    "coediting": false,
    "comment_count": 0,
    "created_at_as_seconds": 1438855324,
    "created_at_in_words": "1分未満",
    "created_at": "2015-08-06 19:02:04 +0900",
    "id": 421379,
    "lgtm_count": 0,
    "raw_body": "test\n",
    "stock_count": 0,
    "stock_users": [

    ],
    "tags": [
      {
        "name": "test",
        "url_name": "test",
        "versions": [

        ]
      }
    ],
    "title": "Test",
    "updated_at": "2015-08-06 19:02:04 +0900",
    "updated_at_in_words": "1分未満",
    "url": "https://example.qiita.com/r7kamura/items/a09e2f506c04aca3397a",
    "user": {
      "id": 4365,
      "profile_image_url": "https://secure.gravatar.com/avatar/089127ffb92a19d3d37815673cca06dc?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png",
      "url_name": "r7kamura"
    },
    "uuid": "a09e2f506c04aca3397a"
  },
  "model": "item",
  "user": {
    "id": 4365,
    "profile_image_url": "https://secure.gravatar.com/avatar/089127ffb92a19d3d37815673cca06dc?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png",
    "url_name": "r7kamura"
  }
}

ItemDestroyed

記事が削除されたときに送信されます。

Payload

プロパティ名 説明
action String "destroyed"
model String "item"
item Item 削除された記事

ItemUpdated

記事が更新されたときに送信されます。

Payload

プロパティ名 説明
action String "updated"
message String ユーザーが入力した変更内容の概要
model String "item"
item Item 更新された記事
user User 更新したユーザー

CommentCreated

コメントが作成されたときに送信されます。

Payload

プロパティ名 説明
action String "created"
model String "comment"
comment Comment 作成されたコメント
item Item コメントの紐付いている記事

Example

request-body-example
{
  "action": "created",
  "comment": {
    "body": "<p>test</p>\n",
    "created_at": "2015-08-06 19:04:06 +0900",
    "id": 305242,
    "raw_body": "test\n",
    "updated_at": "2015-08-06 19:04:06 +0900",
    "url": "https://example.qiita.com/r7kamura/items/a09e2f506c04aca3397a#comment-c47ccda86aca8d03c5d8",
    "user": {
      "id": 4365,
      "profile_image_url": "https://secure.gravatar.com/avatar/089127ffb92a19d3d37815673cca06dc?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png",
      "url_name": "r7kamura"
    },
    "uuid": "c47ccda86aca8d03c5d8"
  },
  "item": {
    "body": "<p>test</p>\n",
    "coediting": false,
    "comment_count": 1,
    "created_at_as_seconds": 1438855324,
    "created_at_in_words": "2分",
    "created_at": "2015-08-06 19:02:04 +0900",
    "id": 421379,
    "lgtm_count": 0,
    "raw_body": "test\n",
    "stock_count": 0,
    "stock_users": [

    ],
    "tags": [
      {
        "name": "test",
        "url_name": "test",
        "versions": [

        ]
      }
    ],
    "title": "Test",
    "updated_at": "2015-08-06 19:02:04 +0900",
    "updated_at_in_words": "2分",
    "url": "https://example.qiita.com/r7kamura/items/a09e2f506c04aca3397a",
    "user": {
      "id": 4365,
      "profile_image_url": "https://secure.gravatar.com/avatar/089127ffb92a19d3d37815673cca06dc?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png",
      "url_name": "r7kamura"
    },
    "uuid": "a09e2f506c04aca3397a"
  },
  "model": "comment"
}

CommentDestroyed

コメントが削除されたときに送信されます。

Payload

プロパティ名 説明
action String "destroyed"
model String "comment"
comment Comment 削除されたコメント
item Item コメントの紐付いている記事

CommentUpdated

コメントが更新されたときに送信されます。

Payload

プロパティ名 説明
action String "updated"
model String "comment"
comment Comment 更新されたコメント
item Item コメントの紐付いている記事

MemberAdded

チームメンバーが追加されたときに送信されます。

Payload

プロパティ名 説明
action String "added"
model String "member"
user User 追加されたユーザー

Example

request-body-example
{
  "action": "added",
  "model": "member",
  "user": {
    "id": 4365,
    "profile_image_url": "https://secure.gravatar.com/avatar/089127ffb92a19d3d37815673cca06dc?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png",
    "url_name": "r7kamura"
  }
}

MemberRemoved

チームメンバーが離脱したときに送信されます。

Payload

プロパティ名 説明
action String "removed"
model String "member"
user User 離脱したユーザー

PingRequested

Webhookの設定画面からテストを行ったときに送信されます。

Payload

プロパティ名 説明
action String "requested"
model String "ping"
message String "ping"

Example

request-body-example
{
  "action": "requested",
  "message": "ping",
  "model": "ping"
}

Types

Payloadの項目で利用した型の内容について説明します。

Comment

記事やプロジェクトに付けられたコメントを表します。

プロパティ名 説明
body String コメント本文のHTML表現
created_at String コメントの作成日時
id Integer コメントの整数のID
raw_body String コメント本文
updated_at String コメントの更新日時
url String コメントのURL
user User コメントの作成者
uuid String コメントのID

Item

Qiita Teamの記事とコメントが付けられたプロジェクトの内容を表します。

プロパティ名 説明
body String 記事本文のHTML表現
coediting Boolean 共同編集かどうか
comment_count Integer コメント数
created_at_as_seconds Integer 記事作成日時のUNIX時間
created_at_in_words String 記事作成日時の簡易表記
created_at String 記事作成日時
id Integer 記事のID
lgtm_count IntegerまたはNull いいね数
raw_body String 記事本文
stock_count IntegerまたはNull ストック数
stock_users Array(User)またはNull ストックしているユーザ一覧
tags Array(Tag) タグ一覧
title String 記事タイトル
updated_at String 更新日時
updated_at_in_words String 更新日時の簡易表記
url String 記事のURL
user User 記事の作成者
uuid StringまたはNull 記事のURLに利用されるID

Tag

記事に付けられるタグを表します。

プロパティ名 説明
name String タグの名前
url_name String タグのURL上での名前
versions Array(String) タグに付けられたバージョン一覧

User

ユーザーを表します。

プロパティ名 説明
id Integer ユーザーの整数のID
profile_image_url String ユーザーのアイコン画像のURL
url_name String ユーザー名