± Revisions rev9

Atsuo Fukaya
Change log: 記事削除時(kind: "post_delete")のwebhookを追加 [skip notice]
Updated by fukayatsu 2016-11-25 16:55:06 +0900
  • # Generic Webhookの概要
  • esaでは、記事やコメントの投稿・更新時に指定されたURLに対してHTTPリクエストを送ることができます。
  • # 設定方法
  • チームのOwnerが https://[your-team].esa.io/team/webhooks から各種Webhookを設定することができます
  • # リクエストの詳細
  • ## HTTPメソッド
  • `POST`
  • ## タイムアウト
  • 20秒(open timeout: 15秒)
  • ## リトライ
  • 1回
  • ※ リクエストがタイムアウトなどで失敗した際、同じリクエストが複数発行される場合があります。その場合は後述する `X-Esa-Delivery` ヘッダを確認することで同一のリクエストかどうかを判断することができます。
  • ## リクエストヘッダー
  • ### Content-Type
  • `application/json`
  • ### User-Agent
  • `esa-Hookshot/v1`
  • ### X-Esa-Delivery
  • 例: `1234`
  • リクエストに対する一意なIDです。
  • ### X-Esa-Signature
  • Generic webhookの設定画面で `Secret (optinal)` を設定した場合にこのヘッダーが追加されます。
  • 例: `sha256=29232dbbdd7947640edb5876581ffaa9991ac5c61f34949cfe7a2980e061b409`
  • endpoint側で、`request.env['HTTP_X_ESA_SIGNATURE']` の値と
  • ```ruby
  • payload = request.body.read
  • OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload)
  • ```
  • の値が一致することを`Rack::Utils.secure_compare`を使って確かめることで、正当なリクエストかどうかを検証することができます。
  • see also: [ppworks/rack-esa_webhooks](https://github.com/ppworks/rack-esa_webhooks)
  • ## json payload
  • ### 記事作成時(kind: "post_create")
  • ```json
  • {
  • "kind": "post_create",
  • "team": {
  • "name": "esa"
  • },
  • "post": {
  • "name": "たいとる",
  • "body_md": "ほんぶん",
  • "body_html": "<p>ほんぶん</p>\n",
  • "message": "Create post.",
  • "wip": false,
  • "number": 1253,
  • "url": "https://example.esa.io/posts/1253"
  • },
  • "user": {
  • "icon": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
  • "thumb_s": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_ms": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_m": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_l": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
  • }
  • },
  • "name": "Atsuo Fukaya",
  • "screen_name": "fukayatsu"
  • }
  • }
  • ```
  • ### 記事更新時(kind: "post_update")
  • ```json
  • {
  • "kind": "post_update",
  • "team": {
  • "name": "esa"
  • },
  • "post": {
  • "name": "たいとる",
  • "body_md": "ほんぶん",
  • "body_html": "<p>ほんぶん</p>\n",
  • "message": "Update post.",
  • "wip": false,
  • "number": 1253,
  • "url": "https://example.esa.io/posts/1253",
  • "diff_url": "https://example.esa.io/posts/1253/revisions/3"
  • },
  • "user": {
  • "icon": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
  • "thumb_s": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_ms": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_m": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_l": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
  • }
  • },
  • "name": "Atsuo Fukaya",
  • "screen_name": "fukayatsu"
  • }
  • }
  • ```
  • ### 記事archive時(kind: "post_archive")
  • ```
  • ```json
  • {
  • "kind": "post_archive",
  • "team": {
  • "name": "esa"
  • },
  • "post": {
  • "name": "Archived/たいとる",
  • "body_md": "ほんぶん",
  • "body_html": "<p>ほんぶん</p>\n",
  • "message": "Archived!",
  • "wip": false,
  • "number": 1253,
  • "url": "https://example.esa.io/posts/1253"
  • },
  • "user": {
  • "icon": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
  • "thumb_s": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_ms": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_m": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_l": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
  • }
  • },
  • "name": "Atsuo Fukaya",
  • "screen_name": "fukayatsu"
  • }
  • }
  • ```
  • ### 記事削除時(kind: "post_delete")
  • ```json
  • {
  • "kind": "post_delete",
  • "team": {
  • "name": "esa"
  • },
  • "post": {
  • "name": "たいとる",
  • "wip": false,
  • "number": 1253
  • },
  • "user": {
  • "icon": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
  • "thumb_s": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_ms": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_m": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_l": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
  • }
  • },
  • "name": "Atsuo Fukaya",
  • "screen_name": "fukayatsu"
  • }
  • }
  • ```
  • ### コメント作成時(kind: "comment_create")
  • ```json
  • {
  • "kind": "comment_create",
  • "team": {
  • "name": "esa"
  • },
  • "post": {
  • "name": "Archived/たいとる",
  • "body_md": "ほんぶん",
  • "body_html": "<p>ほんぶん</p>\n",
  • "message": "Update post.",
  • "wip": false,
  • "number": 1253,
  • "url": "https://example.esa.io/posts/1253#comment-6385"
  • },
  • "comment": {
  • "body_md": "こめんと",
  • "body_html": "<p>こめんと</p>\n"
  • },
  • "user": {
  • "icon": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
  • "thumb_s": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_ms": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_m": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_l": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
  • }
  • },
  • "name": "Atsuo Fukaya",
  • "screen_name": "fukayatsu"
  • }
  • }
  • ```
  • ### メンバー追加時(kind: "member_join")
  • ```json
  • {
  • "kind": "member_join",
  • "team": {
  • "name": "esa"
  • },
  • "user": {
  • "icon": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
  • "thumb_s": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_ms": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_m": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
  • },
  • "thumb_l": {
  • "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
  • }
  • },
  • "name": "Atsuo Fukaya",
  • "screen_name": "fukayatsu"
  • }
  • }
  • ```

Generic Webhookの概要

esaでは、記事やコメントの投稿・更新時に指定されたURLに対してHTTPリクエストを送ることができます。

設定方法

チームのOwnerが https://[your-team].esa.io/team/webhooks から各種Webhookを設定することができます

リクエストの詳細

HTTPメソッド

POST

タイムアウト

20秒(open timeout: 15秒)

リトライ

1回

※ リクエストがタイムアウトなどで失敗した際、同じリクエストが複数発行される場合があります。その場合は後述する X-Esa-Delivery ヘッダを確認することで同一のリクエストかどうかを判断することができます。

リクエストヘッダー

Content-Type

application/json

User-Agent

esa-Hookshot/v1

X-Esa-Delivery

例: 1234

リクエストに対する一意なIDです。

X-Esa-Signature

Generic webhookの設定画面で Secret (optinal) を設定した場合にこのヘッダーが追加されます。

例: sha256=29232dbbdd7947640edb5876581ffaa9991ac5c61f34949cfe7a2980e061b409

endpoint側で、request.env['HTTP_X_ESA_SIGNATURE'] の値と

ruby
payload = request.body.read
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload)

の値が一致することをRack::Utils.secure_compareを使って確かめることで、正当なリクエストかどうかを検証することができます。

see also: ppworks/rack-esa_webhooks

json payload

記事作成時(kind: "post_create")

json
{
    "kind": "post_create",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Create post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
json
{
    "kind": "post_create",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Create post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}

記事更新時(kind: "post_update")

json
{
    "kind": "post_update",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Update post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253",
        "diff_url": "https://example.esa.io/posts/1253/revisions/3"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
json
{
    "kind": "post_update",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Update post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253",
        "diff_url": "https://example.esa.io/posts/1253/revisions/3"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}

記事archive時(kind: "post_archive")

{
    "kind": "post_archive",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "Archived/たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Archived!",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
json
{
    "kind": "post_archive",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "Archived/たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Archived!",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}

コメント作成時(kind: "comment_create")

記事削除時(kind: "post_delete")

json
{
    "kind": "comment_create",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "Archived/たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Update post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253#comment-6385"
    },
    "comment": {
        "body_md": "こめんと",
        "body_html": "<p>こめんと</p>\n"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
json
{
    "kind": "post_delete",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "たいとる",
        "wip": false,
        "number": 1253
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}

メンバー追加時(kind: "member_join")

コメント作成時(kind: "comment_create")

json
{
    "kind": "member_join",
    "team": {
        "name": "esa"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
json
{
    "kind": "comment_create",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "Archived/たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Update post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253#comment-6385"
    },
    "comment": {
        "body_md": "こめんと",
        "body_html": "<p>こめんと</p>\n"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}

メンバー追加時(kind: "member_join")

json
{
    "kind": "member_join",
    "team": {
        "name": "esa"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
# Generic Webhookの概要

esaでは、記事やコメントの投稿・更新時に指定されたURLに対してHTTPリクエストを送ることができます。

# 設定方法
チームのOwnerが https://[your-team].esa.io/team/webhooks から各種Webhookを設定することができます

# リクエストの詳細
## HTTPメソッド
`POST`

## タイムアウト
20秒(open timeout: 15秒)

## リトライ
1回

※ リクエストがタイムアウトなどで失敗した際、同じリクエストが複数発行される場合があります。その場合は後述する `X-Esa-Delivery` ヘッダを確認することで同一のリクエストかどうかを判断することができます。

## リクエストヘッダー
### Content-Type
`application/json`

### User-Agent
`esa-Hookshot/v1`

### X-Esa-Delivery
例: `1234`

リクエストに対する一意なIDです。


### X-Esa-Signature

Generic webhookの設定画面で `Secret (optinal)` を設定した場合にこのヘッダーが追加されます。

例: `sha256=29232dbbdd7947640edb5876581ffaa9991ac5c61f34949cfe7a2980e061b409`


endpoint側で、`request.env['HTTP_X_ESA_SIGNATURE']` の値と

```ruby
payload = request.body.read
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload)
```

の値が一致することを`Rack::Utils.secure_compare`を使って確かめることで、正当なリクエストかどうかを検証することができます。

see also: [ppworks/rack-esa_webhooks](https://github.com/ppworks/rack-esa_webhooks)

## json payload

### 記事作成時(kind: "post_create")

```json
{
    "kind": "post_create",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Create post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
```

### 記事更新時(kind: "post_update")

```json
{
    "kind": "post_update",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Update post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253",
        "diff_url": "https://example.esa.io/posts/1253/revisions/3"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
```

### 記事archive時(kind: "post_archive")
```json
{
    "kind": "post_archive",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "Archived/たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Archived!",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
```

### 記事削除時(kind: "post_delete")

```json
{
    "kind": "post_delete",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "たいとる",
        "wip": false,
        "number": 1253
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
```

### コメント作成時(kind: "comment_create")

```json
{
    "kind": "comment_create",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "Archived/たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Update post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253#comment-6385"
    },
    "comment": {
        "body_md": "こめんと",
        "body_html": "<p>こめんと</p>\n"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
```

### メンバー追加時(kind: "member_join")

```json
{
    "kind": "member_join",
    "team": {
        "name": "esa"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}
```

Generic Webhookの概要

esaでは、記事やコメントの投稿・更新時に指定されたURLに対してHTTPリクエストを送ることができます。

設定方法

チームのOwnerが https://[your-team].esa.io/team/webhooks から各種Webhookを設定することができます

リクエストの詳細

HTTPメソッド

POST

タイムアウト

20秒(open timeout: 15秒)

リトライ

1回

※ リクエストがタイムアウトなどで失敗した際、同じリクエストが複数発行される場合があります。その場合は後述する X-Esa-Delivery ヘッダを確認することで同一のリクエストかどうかを判断することができます。

リクエストヘッダー

Content-Type

application/json

User-Agent

esa-Hookshot/v1

X-Esa-Delivery

例: 1234

リクエストに対する一意なIDです。

X-Esa-Signature

Generic webhookの設定画面で Secret (optinal) を設定した場合にこのヘッダーが追加されます。

例: sha256=29232dbbdd7947640edb5876581ffaa9991ac5c61f34949cfe7a2980e061b409

endpoint側で、request.env['HTTP_X_ESA_SIGNATURE'] の値と

ruby
payload = request.body.read
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload)

の値が一致することをRack::Utils.secure_compareを使って確かめることで、正当なリクエストかどうかを検証することができます。

see also: ppworks/rack-esa_webhooks

json payload

記事作成時(kind: "post_create")

json
{
    "kind": "post_create",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Create post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}

記事更新時(kind: "post_update")

json
{
    "kind": "post_update",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Update post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253",
        "diff_url": "https://example.esa.io/posts/1253/revisions/3"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}

記事archive時(kind: "post_archive")

json
{
    "kind": "post_archive",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "Archived/たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Archived!",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}

記事削除時(kind: "post_delete")

json
{
    "kind": "post_delete",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "たいとる",
        "wip": false,
        "number": 1253
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}

コメント作成時(kind: "comment_create")

json
{
    "kind": "comment_create",
    "team": {
        "name": "esa"
    },
    "post": {
        "name": "Archived/たいとる",
        "body_md": "ほんぶん",
        "body_html": "<p>ほんぶん</p>\n",
        "message": "Update post.",
        "wip": false,
        "number": 1253,
        "url": "https://example.esa.io/posts/1253#comment-6385"
    },
    "comment": {
        "body_md": "こめんと",
        "body_html": "<p>こめんと</p>\n"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}

メンバー追加時(kind: "member_join")

json
{
    "kind": "member_join",
    "team": {
        "name": "esa"
    },
    "user": {
        "icon": {
            "url": "http://img.esa.io/uploads/production/users/1/icon/402685a258cf2a33c1d6c13a89adec92.png",
            "thumb_s": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_s_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_ms": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_ms_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_m": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
            },
            "thumb_l": {
                "url": "http://img.esa.io/uploads/production/users/1/icon/thumb_l_402685a258cf2a33c1d6c13a89adec92.png"
            }
        },
        "name": "Atsuo Fukaya",
        "screen_name": "fukayatsu"
    }
}