kintone Webhookの基本とカスタマイズ検証：通知内容の確認

## はじめに
こんにちは！かねごん（[@hrbk25](https://x.com/hrbk25)）です！

今回はkintoneの**Webhook**に関する内容になります！

Webhookにより、kintoneから外部連携サービスに、通知を送信することはよくありますよね。

ただ、kintoneのアプリで値をセットするカスタマイズなどを行っている場合に、「Webhookの通知内容に、セットした値がちゃんと反映されているよね？？？」と思うことがあったので、実際に検証した内容を備忘録としてまとめました。

### kintone Webhookとは

https://jp.cybozu.help/k/ja/user/app_settings/set_webhook/webhook.html


> kintoneでWebhookを利用すると、kintoneのアプリで特定の操作が行われた際に、その内容を指定した外部サービスに送信します。
たとえば、レコードが追加されたときにその内容をチャットサービスに投稿する、といった連携を、プログラムを書くことなく設定できます。


## どんな人向けの記事か
- kintone の Webhook を使っている方
- kintone のカスタマイズを始めたばかりの方


## kintone JavaScript API や kintone REST API で更新したデータは Webhookで通知されるのか？

今回は、kintone JavaScript API や REST API を使用して値をセットした場合、Webhook でどのようなデータが通知されるのかを検証します。

### 前提：Webhookの通知のタイミング

:::note info
ポイント
kintoneが対応している「通知を送信する条件」は、以下の通りで、**ブラウザの画面上の操作だけでなく、kintone REST APIによる操作でも通知されます。**

- レコードの追加
- レコードの編集
- レコードの削除
- コメントの書き込み
- ステータスの更新
:::



### 準備：Webhookの確認とアプリの設定

今回は、「Webhookを使ってみよう」にある [webhook.site](https://webhook.site/) を使用して、通知内容を確認します。詳細は以下をご参照ください。


https://cybozu.dev/ja/tutorials/hello-kinapi/webhook/

また、以下のようなフィールドを持つサンプルアプリを作成しました。
- 「文字列」：”値は変更されていません！”（初期値）
- 「フラグ」：”ON”、”OFF”

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3582762/9690c2c2-37fd-819e-da47-dfebeddd02da.png)


### kintone JavaScript APIを使った場合

今回は、こちらのkintone JavaScript APIに関する[ドキュメント](https://cybozu.dev/ja/kintone/docs/js-api/events/event-object-actions/#record-create-overwrite-field-values) の機能を使っています。

以下 3 つのイベントとWebhookの設定条件を試しました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3582762/01daf3e8-625c-cc21-f1c9-48b3b2e3f789.png)

1. レコード追加画面を保存したとき 
2.  レコード一覧画面インライン編集で保存するとき
3. プロセス管理のアクションを実行したとき

コードの例は以下の通りです：


```javascript
kintone.events.on('イベント', (event) => {
  event.record['文字列'].value = '値を変更しました！';
  return event; 
});
```

#### 結果
**カスタマイズで値を変更した後のデータ**がWebhookに含まれていることが確認できました。



![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3582762/f788615a-4221-9647-f436-9b9c9c5a7bc4.png)


| イベント                                   | Webhook設定        | 結果 |
|------------------------------------------|-------------------|------|
| レコード追加画面を保存したとき             | レコードの追加       | **OK**   |
| レコード一覧画面インライン編集で保存するとき | レコードの編集       | **OK**   |
| プロセス管理のアクションを実行したとき     | ステータスの更新     | **OK**   |

#### プチまとめ
- 今回使用したkintone JavaScript API のカスタマイズ内容は、Webhookの通知内容に含まれる。



### kintone REST APIを使った場合

今回は、こちらのkintone REST APIに関する[ドキュメント](https://cybozu.dev/ja/id/607d2f57a86f03ca70588ab8/#update-record) の機能を使っています。

以下2つのWebhookの設定をして、レコード更新処理を試してみました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3582762/2de55aab-4666-43ff-d1f5-505bb1917d28.png)

- レコード追加画面の保存が成功したときのイベントハンドラー内で、同じレコードの「フラグ」を”ON”から”OFF”に更新する。

コードの例は以下の通りです：

```javascript
    kintone.events.on('app.record.create.submit.success', async (event) => {
        const appId = kintone.app.getId(); 
        const recordId = event.recordId; 

        try {
           
            const updateData = {
                app: appId,
                id: recordId,
                record: {
                    "フラグ": { value: 'OFF' } 
                }
            };
            await kintone.api('/k/v1/record', 'PUT', updateData);
        } catch (error) {
            console.error(error);
        }
        return event; 
    });
```

#### 結果

以下のような通知内容が確認できました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3582762/7f1563e6-2d52-63dc-aef2-266778e3533b.png)

一瞬 ん？となるかもしれないですが、以下の内容によりWebhookの通知が行われています。

| Webhook設定                                   | 詳細        | 
|------------------------------------------|-------------------|
| レコードの追加 | 「レコード追加画面の保存が成功したとき」の、イベント発生時に"レコードの追加" の通知が行われる。|
| レコードの編集　| 「レコード追加画面の保存が成功したとき」の、kintone REST APIによる更新（PUT）後に、”レコードの編集”の通知が行われる。|


#### プチまとめ
- 前提の**ポイント**でもあったように、kintone REST APIによる更新操作もWebhookの通知が行われる。
- [kintone REST API](https://cybozu.dev/ja/kintone/docs/rest-api/)に記載の**HTTPメソッド**や**URL**を確認し、Webhookの条件を検討する必要がある。


## さいごに
いかがでしたでしょうか？

今回は **Webhook** をテーマに、カスタマイズ内容が通知にどう反映されるかを検証しました。
「この場合どうなるんだっけ？」と思ったときに、ぜひこの記事を参考にしていただければ幸いです！

また、今回の検証を通じて、Webhook の仕組みや挙動について、まだまだ学ぶべきことがあると実感しました。
今後も引き続き、さまざまなケースを試しながら理解を深めていきたいと思います！