Webhook

User can configure project-level webhooks to let Bytebase post messages to the configured webhook endpoint upon various events.

bb-project-webhooks

Supported events#

Issue creation - Post message when issue belonging to the configured project has been created.
Issue status change - Post message when the status of the issue belonging to the configured project has been changed.
Issue stage status change - Post message when issue's enclosing stage status has been changed.
Issue task status change - Post message when issue's enclosing task status has been changed.
Issue info change - Post message when issue's basic info such as assignee, title, description has been changed.
Issue comment creation - Post message when new comment added to the issue.

The following events support sending direct messages/notifications to related users, make sure you have:

enabled the Enable direct messages option to enable this feature.
configured the IM integration to send messages to related users.

Issue approval needed - Post message when issue needs approval.
Issue approved - Post message when issue has been approved.
Issue rollout needed - Post message when issue needs rollout.

Supported webhook endpoints#

Slack#

Official guide

Go to https://api.slack.com/apps.
Click Create New App.
Choose From an app manifest.
Pick your workspace to develop the app and click Next.

Replace the existing JSON with this manifest content and click Next.

{
  "display_information": {
      "name": "Bytebase Bot"
  },
  "features": {
      "bot_user": {
          "display_name": "Bytebase Bot",
          "always_online": false
      }
  },
  "oauth_config": {
      "scopes": {
          "bot": [
              "users:read",
              "users:read.email",
              "channels:manage",
              "groups:write",
              "im:write",
              "chat:write",
              "mpim:write"
          ]
      }
  },
  "settings": {
      "org_deploy_enabled": false,
      "socket_mode_enabled": false,
      "token_rotation_enabled": false
  }
}

Click Create.
Click Install to Workspace and click Allow.
Go to Features > OAuth & Permissions and copy the Bot User OAuth Token.
Go back to Bytebase and paste the Bot User OAuth Token to the Token field under Integration > IM.
Go to Integration > Webhooks in a project, add a webhook, check all the events you want to send direct messages, and click Create.

Go to https://open-dev.dingtalk.com/.
Select Application Development, click Create Application.
Select Credentials and Basic Information on the left sidebar. Obtain the Client ID and Client Secret.
Select Permission Management, grant the following permissions:
- qyapi_get_member_by_mobile
- qyapi_robot_sendmsg
Select Add Application Capability, add the Robot capability. Configure the robot, and for Message receiving mode select Stream mode. In "Robot Configuration", click Copy RobotCode to obtain the Robot Code. Publish the robot.
Select Version Management and Release. Click Create New Version. Fill in the relevant information, then Save and Directly Publish.
Go back to Bytebase and fill Client ID, Client Secret and Robot Code fields under Integration > IM.
Go to Integration > Webhooks in a project, add a webhook, check all the events you want to send direct messages, and click Create.

DingTalk allows to specify a list of keywords in the security setting to protect webhook endpoint. You can add "Bytebase" to that keyword list.

Feishu (Lark)#

Official guide

Feishu (Lark) allows to specify a list of keywords in the security setting to protect webhook endpoint. You can add "Bytebase" to that keyword list.

Go to https://open.feishu.cn/app.
Click Create Custom App, fill the form and click Create.
Click Add Features on the left sidebar, add the Bot feature.
Click Permisions & Scopes on the left sidebar, find and add the following permissions:
- contact:user.id:readonly
- im:message:send_as_bot
Click Create Version.
Configure availability.
Go back to Bytebase and fill App Id and App Secret fields under Integration > IM.
Go to Integration > Webhooks in a project, add a webhook, check all the events you want to send direct messages, and click Create.

WeCom#

WeCom does not provide its own official guide. Please follow this similar setup from Tencent Cloud instead.

Go to https://work.weixin.qq.com/wework_admin/frame#apps.
Click the tab My Company, and then you can find Company ID in the Company Information.
Click the tab App Management, and choose Create an app under Self-built.
Open the app,
1. Find AgentId and Secret.
2. Configure Allowed users.
3. Configure Company's Trusted IP to your Bytebase instance IP.
Make sure the user's email in Bytebase is the same as the user's email (not External account) in WeCom.
Go back to Bytebase and fill Corp Id, Agent Id and Secret fields under Integration > IM.
Go to Integration > Webhooks in a project, add a webhook, check all the events you want to send direct messages, and click Create.

Custom#

Custom is used to integrate with your own services via webhook.

You need to implement the webhook server yourself, it doesn't work out of the box.

API Definition as follow:

HTTP Method

POST
Request Header

Key Value Description
Content-Type application/json JSON content

Key	Value	Description
`Content-Type`	`application/json`	JSON content

Request Body

Key	Type	Description
`level`	String	One of: `INFO` `SUCCESS` `WARN` `ERROR`
`activity_type`	String	One of: `bb.issue.create` `bb.issue.comment.create` `bb.issue.field.update` `bb.issue.status.update` `bb.pipeline.task.status.update`
`title`	String	Webhook title
`description`	String	Webhook description
`link`	String	Webhook link
`creator_id`	Integer	Updater id
`creator_name`	Integer	Updater name
`created_ts`	Integer	Webhook create timestamp
`issue`	Object	Issue Object
`- id`	Integer	Issue ID
`- name`	String	Issue Name
`- status`	String	Issue Status, one of: `OPEN` `DONE` `CANCELED`
`- type`	String	Issue Type, one of: `bb.issue.database.create` `bb.issue.database.grant` `bb.issue.database.schema.update` `bb.issue.database.schema.update.ghost` `bb.issue.database.data.update` `bb.issue.database.rollback` `bb.issue.database.data.export`
`- description`	String	Issue Description
`project`	Object	Project Object
`- id`	Integer	Project ID
`- name`	String	Project Name

Response Body

Key Type Description
code String Zero if success, non-zero if failed
message String Some error message
Response StatusCode
- 200, OK
- Other, if any error

Key	Type	Description
`code`	String	Zero if success, non-zero if failed
`message`	String	Some error message

Example Request Body

{
  "level": "INFO",
  "activity_type": "bb.issue.created",
  "title": "example webhook",
  "description": "example description",
  "link": "example link",
  "creator_id": 1,
  "creator_name": "Bytebase",
  "created_ts": 1651212107,
  "issue": {
    "id": 1,
    "name": "example issue",
    "status": "OPEN",
    "type": "bb.issue.database.create",
    "description": "This is a test issue"
  },
  "project": {
    "id": 1,
    "name": "demo"
  }
}

Example Response Body

Success
```
{
  "code": 0,
  "message": ""
}
```

Failed

{
    "code": 400
    "message": "Ops, some error occured!"
}

Webhook

Supported events#

Supported webhook endpoints#

Slack#

Configure sending direct messages to related users#

Discord#

Microsoft Teams#

DingTalk#

Configure sending direct messages to related users#

Feishu (Lark)#

Configure sending direct notifications to related users#

WeCom#

Configure sending direct messages to related users#

Custom#