Introduction
This article is an introduction to setting up Webhooks, a new feature implemented in the 2017 February update. You can utilize the Webhook feature to connect to services outside of kintone.
What are Webhooks?
In kintone, each app has an option to set up Webhooks.
The kintone Webhook feature allows data of a record of an app to be sent to a particular endpoint in a certain format. This data can be sent at the following timings:
-When a new record is added
-When a record is saved after editing
-When a record is deleted
-When a user posts a comment to a record
-When a status of your process management is updated
Why set up a Webhook?
The kintone Webhooks is a good way to send data to an endpoint without the use of coding. Setting up a webhook will only involve stating an endpoint, and the timing you would like the data to be sent.
You would though, have to set something up on the endpoint side so that this data could be caught, and be used to your advantage. If you would like to do this without coding, you can use a cloud service like Zapier to catch the kintone Webhook data, and connect it to other services.
How to set up a Webhook
First, before we actually go into setting up the Webhook, we advise you to check your field settings first. When kintone sends out data using the Webhook feature, they are going to send out Field Code names, rather than the Field names to the endpoint.
Make sure to change the Field Code of your fields of you app, so you can identify which Field Code matches which Field name.
Once that's done, follow these steps to set up your Webhook:
- In the App Settings, click on "Webhooks".
- Click on the + sign to add a new Webhook setting.
- Set a name for your Webhook. This is just giving it a name so you can identify it later on. You can set this to whatever you like.
- Set a Webhook Endpoint. This should be in a form of a URL, and should be generated by the service that you want to connect to. For example, if you were to use Webhooks by Zapier Integrations, then a Webhook URL should be generated by Zapier during one of the steps for setting up your Zap.
- Select an Event (or timing) for when you want data to be sent to the Webhook endpoint.
- Keep the "Activation" checkbox checked. You can un-check this any time you want to stop sending data to the Webhook endpoint.
- Click "Save" when you are done.
- Click on "Back to App Settings" and "Update App" to have these settings deployed to your app.
Now whenever you preform an action selected in the "Events", data from your record will be sent to the Endpoint URL.
Data sent by the Webhook
The kintone record data sent by the Webhooks are as follows:
Events: Record is added / Record is edited / Status is changed
| Parameter | Type | Details |
|---|---|---|
| id | String | A unique ID given to the webhook notification. |
| type | String | The event type. Record is added: ADD_RECORD Record is edited: UPDATE_RECORD Status is changed: UPDATE_STATUS |
| app | Array | An array consisting of App data. |
| app[].id | String | The App ID. |
| app[].name | String | The App name. |
| record | Array | An array consisting of record data. The format is the same as what the Get Record REST API uses: |
| recordTitle | String | The Title Field of the record. Title Fields of records can be edited in the App's settings. |
| url | String | The URL of the record. |
Events: Record is deleted
| Parameter | Type | Details |
|---|---|---|
| id | String | A unique ID given to the webhook notification. |
| type | String | The event type. Record is deleted: DELETE_RECORD |
| app | Array | An array consisting of App data. |
| app[].id | String | The App ID. |
| app[].name | String | The App name. |
| recordId | String | The record number. |
| deleteBy | Array | An array consisting of data of the user who deleted the record. |
| deleteBy[].code | String | The User Code (log in name). |
| deleteBy[].name | String | The User's display name. |
| deleteAt | String | The date and time of when the record was deleted. |
Events: Comment is posted
| Parameter | Type | Details |
|---|---|---|
| app | Array | An array consisting of App data. |
| app[].id | String | The App ID. |
| app[].name | String | The App name. |
| comment | Array | An array consisting of comment data. The format is the same as what the Get Comments REST API uses: |
| id | String | A unique ID given to the webhook notification. |
| recordId | String | The record number. |
| type | String | The event type. Comment is posted： ADD_RECORD_COMMENT |
| url | String | The URL of the comment. |
Cloud services for Webhook Endpoints
There are several cloud services that could be set as the Endpoints.
We will keep this list updated:
- Zapier: Webhooks by Zapier Integrations trigger
- Microsoft Flow: Request Trigger