Skip to main content
  • Home
  • API
  • Incoming and outgoing webhooks

Incoming and outgoing webhooks

Abstract

Both incoming and outgoing webhooks can be set up with the Bitrise API. They are important for automatic build triggering and the reporting of build events to other services.

Both incoming and outgoing webhooks can be set up with the Bitrise API. They are important for automatic build triggering and the reporting of build events to other services.

Table 1. Endpoints related to incoming and outgoing webhooks

Endpoints

Function

Required role on the app's team

POST /apps/{app-slug}/register-webhook

Register an incoming webhook for a specific application.

Owner or Admin

GET /apps/{app-slug}/outgoing-webhooks

List the outgoing webhooks of an app.

Owner or Admin

POST /apps/{app-slug}/outgoing-webhooks

Create an outgoing webhook for an app.

Owner or Admin

PUT /apps/{app-slug}/outgoing-webhooks/{app-webhook-slug}

Update an outgoing webhook of an app.

Owner or Admin

DELETE /apps/{app-slug}/outgoing-webhooks/{app-webhook-slug}

Delete an outgoing webhook of an app.

Owner or Admin

Registering an incoming webhook with the API

Incoming webhooks enable users to set up automatic triggers for their apps on Bitrise: for example, a Bitrise webhook registered on GitHub can automatically trigger a build when code is pushed to the GitHub repository.

Required role

You must have an admin or owner role on the app's team to manage incoming or outgoing webhooks using the API.

For a complete list of user roles and role cheatsheets, check User roles on project teams.

To set up a webhook, you must connect your Bitrise account to your Git provider account: this allows Bitrise to register the webhook automatically.

Register a webhook by calling the register-webhook endpoint with an existing app slug:

curl -X POST -H 'Authorization: ACCESS-TOKEN' 'https://api.bitrise.io/v0.1/apps/APP-SLUG/register-webhook'

This will register a webhook to the Git provider of the app. Afterwards, you can set up automatic triggers either on the website or via the Trigger Map in the app’s bitrise.yml file.

Creating outgoing webhooks with the API

Outgoing webhooks enable integration with other services: specifically, they are used to notify other services. Currently, only build event notifications are supported. There are two supported build events: triggering a build and finishing a build.

Build status reports

Notifying your Git provider about the build status does not require outgoing webhooks.

To set up an outgoing webhook for an application, you need to specify the app itself and at least two of the creation parameters:

  • The webhook URL: you can get this from the service you want to integrate with Bitrise.

  • The events that trigger the webhook. Currently, this takes two possible values: all and build.

Required role

You must have an admin or owner role on the app's team to manage incoming or outgoing webhooks using the API.

For a complete list of user roles and role cheatsheets, check User roles on project teams.

You can also set up custom headers by specifying a key/value pair in the request.

Example 1. A new outgoing webhook with the URL 'example.webhook.com'

Request:

curl -X POST "https://api.bitrise.io/v0.1/apps/APP-SLUG/outgoing-webhooks" -H "accept: application/json" -H "Authorization: ACCESS-TOKEN" -H "Content-Type: application/json" -d "{ \"events\": [ \"build\" ], \"url\": \"example.webhook.com\", \"headers\": { \"KEY\": \"value\" }}"

Response:

{
  "slug": "01D72ARNH4KR7KMW3DG3NBKXRK",
  "url": "example.webhook.com",
  "events": [
    "build"
  ],
  "headers": {
    "KEY": "value"
  },
  "registered_by_addon":false,
  "created_at": "2019-03-28T14:20:22.436825Z",
  "updated_at": "2019-03-28T14:20:22.436825Z"
}

Modifying and deleting outgoing webhooks with the API

To modify an existing webhook, you need to specify all the mandatory parameters in your request. In other words, even if you only want to change the URL, the request still has to contain a valid value for the events parameter.

Required role

You must have an admin or owner role on the app's team to manage incoming or outgoing webhooks using the API.

For a complete list of user roles and role cheatsheets, check User roles on project teams.

Example 1. Modifying an outgoing webhook

Request:

curl -X PUT "https://api.bitrise.io/v0.1/apps/APP-SLUG/outgoing-webhooks/WEBHOOK-SLUG" -H "accept: application/json" -H "Authorization: ACCESS-TOKEN" -H "Content-Type: application/json" -d" { \"events\": [ \"all\" ], \"headers\": { \"Modified\": \"1212\" }, \"url\": \"example2.webhook.com\"}"

Response:

{
  "data": {
    "slug": "WEBHOOK-SLUG",
    "url": "example2.webhook.com",
    "events": [
      "all"
    ],
    "headers": {
      "Modified": "1212"
    },
    "registered_by_addon": false,
    "created_at": "2019-03-28T14:20:22.436825Z",
    "updated_at": "2019-03-28T14:20:22.436825Z"
  }
}

To delete an outgoing webhook, all you need to do is provide the app slug and the webhook slug in your request:

curl -X DELETE "https://api.bitrise.io/v0.1/apps/APP-SLUG/outgoing-webhooks/WEBHOOK-SLUG" -H "accept: application/json" -H "Authorization: ACCESS-TOKEN"
In this section:
triggering