Project 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, 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

  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

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.

  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.

  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.

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

    KeyValueDescription
    Content-Typeapplication/jsonJSON content
  • Request Body

    KeyTypeDescription
    levelStringOne of:
      INFO
      SUCCESS
      WARN
      ERROR
    activity_typeStringOne of:
      bb.issue.create
      bb.issue.comment.create
      bb.issue.field.update
      bb.issue.status.update
      bb.pipeline.task.status.update
    titleStringWebhook title
    descriptionStringWebhook description
    linkStringWebhook link
    creator_idIntegerUpdater id
    creator_nameIntegerUpdater name
    created_tsIntegerWebhook create timestamp
    issueObjectIssue Object
    - idIntegerIssue ID
    - nameStringIssue Name
    - statusStringIssue Status, one of:
      OPEN
      DONE
      CANCELED
    - typeStringIssue Type, one of:
      bb.issue.database.create
      bb.issue.database.schema.update
      bb.issue.database.schema.update.ghost
      bb.issue.database.data.update
    - descriptionStringIssue Description
    projectObjectProject Object
    - idIntegerProject ID
    - nameStringProject Name
  • Response Body

    KeyTypeDescription
    codeStringZero if success, non-zero if failed
    messageStringSome 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"
  },
  "project": {
    "id": 1,
    "name": "demo"
  }
}

Example Response Body

  • Success
    {
      "code": 0,
      "message": ""
    }
  • Failed
    {
        "code": 400
        "message": "Ops, some error occured!"
    }
Edit this page on GitHub

Subscribe to Newsletter

By subscribing, you agree with Bytebase's Terms of Service and Privacy Policy.