Creating a Webhook in an App

Overview

What is a Webhook?

A Webhook is a feature used to link multiple web services. When Kintone is configured with a Webhook, it can send a notification to external web services whenever any of the following events occur:

  • Record is added
  • Record is edited
  • Record is deleted
  • Record status is updated
  • Comment is posted

I.e. Slack posts a message every time a record is added to an app in Kintone.

A web service must be compatible with Webhook data reception to be connected to Kintone. If the web service is not compatible, it can still be linked with Kintone through other web services such as Zapier and IFTTT. There are examples of linkage established by Webhook in the Kintone developer network for reference, such as this one: Post Messages to Slack.

Please note, a notification will not be sent for the following events:

  • Excel/CSV file imported and records are processed
  • Multiple records are deleted in bulk
  • Records with REST APIs that are used to take actions on multiple records in bulk are processed

For more information, please visit the Kintone Developer Network.

Content of Notifications Being Sent

When Webhook is enabled, Kintone sends notifications in JSON format. The parameters within the notifications vary depending on the event as seen below.

Event: Record is added / Record is edited / Record status is updated

Parameter Type Description
  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 

Example of Notification: 

{
      "id":"01234567-0123-0123-0123-0123456789ab",
      "type":"ADD_RECORD",
      "app":{
            "id":"1",
            "name":"Project management"
      },
      "record":{
            "Record number":{
                  "type":"RECORD_NUMBER",
                  "value":"2"
            },
            ...(omitted)...
            "$revision":{
                  "type":"__REVISION__",
                  "value":"3"
            },
            "$id":{
                  "type":"__ID__",
                  "value":"2"
            }
      },
      "recordTitle":"Visit: Cybozu, Inc.",
      "url":"https://example.cybozu.com/k/1/show#record=2"
}

 

Event: Record is deleted

Parameter Type Description
  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

Example of Notification:

{
      "app":{
            "id":"1",
            "name":"Project management"
      },
      "id":"01234567-0123-0123-0123-0123456789ab",
      "recordId": "2", 
      "deleteBy":{
            "code":"John",
            "name":"John Doe"
      },
      "deleteAt":"2017-07-03T09:38:09Z"
      "type":"DELETE_RECORD"
}

 

Event: Comment is posted

Parameter Type Description
  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

Example of Notification:

{
      "app":{
            "id":"1",
            "name":"Project management"
      },
      "comment":{
            "createdAt":"2012-02-03T09:38:09Z",
            "creator":{
                  "code":"jane",
                  "name":"Jane Doe"
            },
            "id":"11",
            "mentions":[{
                  "code":"jane",
                  "type":"USER"
            },{
                  "code":"org1",
                  "type":"ORGANIZATION"
            },{
                  "code":"group1",
                  "type":"GROUP"
            }],
            "text":"I visited Cybozu, Inc."
      },
      "id":"01234567-0123-0123-0123-0123456789ab",
      "recordId":"2",
      "type":"ADD_RECORD_COMMENT",
      "url":"https://example.cybozu.com/k/1/show#record=2&comment=11"
}

 

Setting up a Webhook

  1. In the web service you wish to connect with Kintone, retrieve the Webhook Endpoint.
  2. Within an app, click the Gear wheel Screen_Shot_2017-07-19_at_9.43.03_AM.png on the right and select the App Settings tab.
  3. Under Customization and Integration, select Webhooks.
  4. Click Screen_Shot_2018-06-05_at_2.43.02_PM.png to add a new Webhook.
  5. Fill in the details of the Webhook.
    • Description: Set a name of up to 64 characters for the Webhook. The entered description is displayed on the Webhook setting list screen.
    • Webhook Endpoint: Insert the url of the Webhook Endpoint from step 1. The entry can be up to 512 characters in length.
    • Events: Specify the events that will send a notification to the Webhook Endpoint.
    • Activation: Select whether to enable this Webhook. This is enabled by default.
  6. Click Save.
  7. Click Back to App Settings and Update App to deploy the Webhook. 

Please note, a maximum of 10 Webhooks can be set. 

Webhook Execution Log

The 10 most recent execution logs can be viewed for each Webhook. Each execution log contains the following information:

  • Whether the notification sent successfully
  • Notification ID
  • Action type
  • User who performed the action
  • Execution date and time

To check for older logs, see the audit log. Please note, the audit log can only be checked by a Kintone Administrator. For further details, see Viewing and Downloading Audit Logs.

How to check an app's Webhook Execution Log:

  1. Within an app, click the Gear wheel Screen_Shot_2017-07-19_at_9.43.03_AM.png on the right and select the App Settings tab.
  2. Under Customization and Integration, select Webhooks. (The Webhook list screen displays if the latest notification was successfully sent.)
  3. Click Check Logs for the Webhook whose logs you wish to check.

If all notifications failed to send, the Webhook may have incorrect settings. If only some of the notifications failed, the cause may be one of the following:

Error Cause
  The number of notifications exceeded 60 in one minute.   For a Webhook, up to 60 notifications can be sent per minute. If more than 60 records are processed in one minute, Webhook notifications will not be sent for any subsequent records that are processed.
 Notifications failed with Kintone errors.   The cause may be one of the following:
  • The size of notification data that was sent exceeded the maximum limit (1 MB).
  • Timeout occurred in Kintone.
  Notifications failed due to an error in the receiving web service.   The cause may be one of the following:
  • The web service receiving the notification was inactive, such as due to maintenance.
  • Timeout occurred in the web service that is receiving the notification.
  • The number of notifications that the web service received exceeded its maximum limit.
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.