Webhook

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

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, you must enable the Enable direct messages option to enable this feature.

• 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

Configure sending direct messages to related users#

1. Go to https://api.slack.com/apps.

2. Click Create New App.

3. Choose From an app manifest.

4. Pick your workspace to develop the app and click Next.

5. 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
     }
   }

6. Click Create.

7. Click Install to Workspace and click Allow.

8. Go to Features > OAuth & Permissions and copy the Bot User OAuth Token.

9. Go back to Bytebase and paste the Bot User OAuth Token to the Token field under Integration > IM.

10. Go to Integration > Webhooks in a project, add a webhook, check all the events you want to send direct messages, and click Create.

Discord#

Official guide

Microsoft Teams#

Official guide

DingTalk#

Official guide

Feishu (Lark)#

Official guide

Configure sending direct notifications to related users#

1. Go to https://open.feishu.cn/app.
2. Click Create Custom App, fill the form and click Create.
3. Click Permisions & Scopes on the left sidebar, find and add the following permissions:
   • contact:user.id:readonly
   • im:message:send_as_bot
4. Click Create Version.
5. Configure availability.

WeCom#

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

Configure sending direct messages to related users#

1. Go to https://work.weixin.qq.com/wework_admin/frame#apps.
2. Click the tab My Company, and then you can find Company ID in the Company Information.
3. Click the tab App Management, and choose Create an app under Self-built.
4. Open the app,
   1. Find AgentId and Secret.
   2. Configure Allowed users.
   3. Configure Company's Trusted IP to your Bytebase instance IP.
5. Make sure the user's email in Bytebase is the same as the user's email (not External account) in WeCom.

Custom#

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

API Definition as follow:

• HTTP Method

  POST

• Request Header

  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

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