Skip to content

Webhook Overview

GitKraken Boards and GitKraken Timelines has sunset at the end of 2022. The below information and features may be out of date. Please read our full announcement and FAQ to learn more.

What are GitKraken Boards Webhooks?

Webhooks allow you to create applications that subscribe to GitKraken Board events. When an event is triggered, a payload is delivered to the webhook's configured URL.

For example, you could create an application utilizing a webhook that posts to a Slack channel whenever a card has been added or deleted from a board.

Who can add Webhooks?

Webhooks can be added to a specific board by an Owner or Admin of the board. Once added, the webhook will trigger each time a subscribed event occurs.

You can add multiple webhooks to a board. If no Owners of the board have Pro, only 1 webhook can be active on that board. If at least one Owner of the board has Pro, the board may have up to 10 active webhooks.

Events

When configuring a webhook, you can select which events will deliever a payload to your server. After creating a webhook, you may edit the webhook to change the event subscriptions.

Every event corresponds to a set of actions that can happen in your board. For example, if a webhook is subscibed to the cards event the configured server will receive payloads every time a card is created, updated, moved, deleted, and so forth.

Here are the current available webhook events:

Name Description
boards Triggered when a board is archived, unarchived, updated, or deleted. It will also trigger whenever board labels and members are added, removed, or modified.
column Triggered when a column is added, moved, archived, deleted or renamed.
cards Triggered when a card on the board is added, copied, moved, archived, unarchived, or deleted. It will also trigger when any fields for a card are modified.
comments Triggered when a comment is added, deleted, or modified on a card the belongs to the board.

Payloads

Each event type has a specific payload format with the relevant event information. In addition to the fields documented for each event, webhook payloads includes a sequence number (sequence).

This number can be used to determine the order payloads were delivered and can also be used by your server or application to verify whether all payloads are delivered.

For example, if your server received a payload with sequence 7 but was expecting sequence 6, you will know that a payload failed to send or be delivered.

Delivery Headers

Payloads delivered to your webhook's configured URL endpoint will contain some special headers:

Header Description
x-gk-event Name of the event type that triggered the delivery.
x-gk-signature The signature generated using the payload and the webhook secret. For more information, checkout our example.

Sample Delivery

Header:

{
  "content-type": "application/json",
  "user-agent": "gk-webhooks",
  "x-gk-event": "columns",
  "x-gk-signature": "sha1=e0340aad257f586732bfd2379c381bc746c87e48"
}

Body:

{
  "action": "added",
  "board": {
    "id": "5bfc13d225ff0b000e6cb830",
    "name": "MEGALOVANIA"
  },
  "sender": {
    "name": "Keif",
    "id": "daec859f-dcd7-40c4-b2d3-6e74ab62426c",
    "username": "keifwebhook"
  },
  "column": {
    "id": "5bfc526b25ff0b000e6cb8ba",
    "name": "In Progress",
    "created_date": "2018-11-26T20:07:07.388Z",
    "created_by": {
      "id": "daec859f-dcd7-40c4-b2d3-6e74ab62426c"
    }
  },
  "sequence": 4
}