# 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")
```
{
    "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")

```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"
    }
}
```