Webhook

A webhook is a standard mechanism for an add-on to listen to in-product events via HTTP callbacks. An add-on can register a webhook in the Atlassian Connect descriptor to listen to events that are fired by Jira or Confluence.

Just to give you an idea of how you can use them in add-ons, here are a few sample webhook events:

  • When an issue is created or closed in Jira
  • When a page is created or updated in Confluence
  • An attachment is viewed in Confluence

If your add-on uses webhooks, you must declare the "read" scope in your atlassian-connect.json descriptor.

Handling the webhook event

To receive webhook events, your add-on needs to include the webhook module declaration in its JSON descriptor. The declaration indicates the add-on relative URL at which it will receive the notification. In other words, the Atlassian application will send an HTTP POST to this resource in response to an application event. The add-on code that handles the POST should process any information passed in the body of the message, as appropriate. Each webhook POST sent to the add-on will also include the authentication headers that allow the add-on to validate the authenticity of that request. Specifically, the JWT token can be found in the "Authorization" HTTP header.

Note that if using Apache and mod_wsgi to serve files to a Django application, the Authentication header is stripped out by default. Extra configuration is required to ensure the Authentication header is visible.

Important: It must be noted that webhook delivery is not guaranteed; it is best effort. When a webhook event is triggered in Jira or Confluence instance then a single HTTP POST is sent to your add-on. If your add-on is down, or there is any network problems between the Atlassian product and your add-on, then you will never receive the webhook event. In general, webhooks are quite reliable; however you must always keep in mind that delivery is not guaranteed.

Variable Substitution

Jira webhooks also provide a way to add and substitute variables in the url. This is similar to context parameters for add-ons. See context parameters.

For example, if we register to listen for one of the project events with a url containing {project.id}, a POST message will be sent to the address with the {project.id} replaced by the id of the project that the event was triggered for.

Filtering

Additional filters may be specified to trigger webhooks only for events satisfying certain conditions. How the filter value is supposed to look like exactly, and whether filtering is available at all, depends on the event type. The following sections describe all the possibilities.

JQL

Issue-related events may be filtered with JQL. Webhooks will be sent only for issues matched by the provided JQL query. Here is an example JQL query that can be put into the "filter" property: "project = TEST AND fixVersion = future".

JQL filtering is supported only by the following event types:

  • jira:issue_created
  • jira:issue_deleted
  • jira:issue_updated
  • comment_created
  • comment_updated
  • comment_deleted
  • issue_property_set
  • issue_property_deleted
  • worklog_created
  • worklog_updated
  • worklog_deleted

Webhook event types

Below is a list of all available webhook events.

Add-on and system events

  • connect_addon_disabled
  • connect_addon_enabled

Issue events

  • jira:issue_created
  • jira:issue_deleted
  • jira:issue_updated

    The supported context parameters are {project.id}, {project.key}, {issue.key}, {issue.id}.

  • issuelink_created
  • issuelink_deleted

Filter events

  • filter_created
  • filter_updated
  • filter_deleted

    There is one supported context parameter: {filter.id}.

Issue properties events

  • issue_property_set
  • issue_property_deleted

    The supported context parameters are {project.id}, {project.key}, {issue.key}, {issue.id}.

Issue Type events

  • issuetype_created
  • issuetype_updated
  • issuetype_deleted

    The supported context parameters are {project.id}, {project.key}, {issuetype.id}.

Attachment events

  • attachment_created
  • attachment_deleted

    The supported context parameters are {attachment.id}, {project.id}, {project.key}, {issue.key}, {issue.id}.

Version events

  • jira:version_created
  • jira:version_deleted
  • jira:version_merged
  • jira:version_updated
  • jira:version_moved
  • jira:version_released
  • jira:version_unreleased

    The supported context parameters are {project.id}, {project.key}, {version.id}.

    Special context parameter for version_merged event is {mergedVersion.id}.

Project events

  • project_created
  • project_updated
  • project_deleted

    The supported context parameters are {project.id}, {project.key}

Project App Events

  • project_app_enabled
  • project_app_disabled

    The supported context parameters are {project.id}, {project.key}, {app.key}

User events

  • user_created
  • user_deleted
  • user_updated

    The supported context parameters are {modifiedUser.accountId}, {modifiedUser.name} (deprecated), {modifiedUser.key} (deprecated)

Feature status events

  • option_voting_changed
  • option_watching_changed
  • option_unassigned_issues_changed
  • option_subtasks_changed
  • option_issuelinks_changed
  • option_timetracking_changed

Comment events

  • comment_created
  • comment_updated
  • comment_deleted

    The supported context parameters are {project.id}, {project.key}, {issue.key}, {issue.id}, {comment.id}.

Worklog events

  • worklog_created
  • worklog_updated
  • worklog_deleted

    The supported context parameters are {project.id}, {project.key}, {issue.key}, {issue.id}, {worklog.id}.

Confluence Webhook events

  • attachment_archived
  • attachment_created
  • attachment_removed
  • attachment_restored
  • attachment_trashed
  • attachment_unarchived
  • attachment_updated
  • attachment_viewed
  • blog_created
  • blog_removed
  • blog_restored
  • blog_trashed
  • blog_updated
  • blog_viewed
  • blueprint_page_created
  • comment_created
  • comment_removed
  • comment_updated
  • connect_addon_disabled
  • connect_addon_enabled
  • content_created
  • content_removed
  • content_restored
  • content_trashed
  • content_updated
  • content_permissions_updated
  • group_created
  • group_removed
  • label_added
  • label_created
  • label_deleted
  • label_removed
  • page_archived
  • page_children_reordered
  • page_created
  • page_copied
  • page_moved
  • page_removed
  • page_restored
  • page_trashed
  • page_unarchived
  • page_updated
  • page_viewed
  • relation_created
  • relation_deleted
  • search_performed
  • space_created
  • space_logo_updated
  • space_permissions_updated
  • space_removed
  • space_updated
  • theme_enabled
  • user_followed
  • user_reactivated
  • user_removed

Example request

1
2
3
4
5
6
7
8
9
10
11

 POST /jira-issue_created?user_id=admin&user_key=admin HTTP/1.1
 Authorization: JWT ...
 Atlassian-Connect-Version: x.x
 Content-Type: application/json
 {
   timestamp: 1426661049725,
   webhookEvent: 'jira:issue_created',
   ...
 }
 

Example responses

All webhooks will post JSON data to the listening add-on. The structure of this JSON differs based on the Atlassian product that sent the event and the event itself. Here are some example webhook events:

All webhook events that are sent because of Jira issue updates will have the following structure.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

 {
   "timestamp"
   "event"
   "user": {
     // See User shape in the linked document
   },
   "issue": {
     // See Issue shape in the linked document
   },
   "changelog" : {
     // See Changelog shape in the linked document
   },
   "comment" : {
     // See Comment shape in in the linked document
   }
 }
 

This is fully documented in Webhooks: Example callback for an issue-related event.

Confluence page_created

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

 {
   "userAccountId": "ff80808154510724015451074c160001",
   "accountType": "customer",
   "page": {
     "creatorAccountId": 'ff80808154510724015451074c160001',
     "spaceKey": "~admin",
     "modificationDate": 1471926079631,
     "lastModifierAccountId": "ff80808154510724015451074c160001",
     "self": "https://cloud-development-environment.atlassian.net/wiki/display/~admin/Some+random+test+page",
     "id": 16777227,
     "title": "Some random test page",
     "creationDate": 1594752539309,
     "contentType": "page",
     "version": 1
   },
   "timestamp": 1471926079645
  }
 

Confluence comment_created

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

 {
   "userAccountId": "ff80808154510724015451074c160001",
   "accountType": "customer",
   "comment": {
     "creatorAccountId": "ff80808154510724015451074c160001",
     "spaceKey": "~admin",
     "parent": {
       "creatorAccountId": "ff80808154510724015451074c160001",
       "spaceKey": "~admin",
       "modificationDate": 1471926079631,
       "lastModifierAccountId": "ff80808154510724015451074c160001",
       "self": "https://cloud-development-environment.atlassian.net/wiki/display/~admin/Some+random+test+page",
       "id": 16777227,
       "title": "Some random test page",
       "creationDate": 1471926079631,
       "contentType": "page",
       "version": 1
     },
     "modificationDate": 1471926091465,
     "lastModifierAccountId": "ff80808154510724015451074c160001",
     "self": "https://cloud-development-environment/wiki/display/~admin/Some+random+test+page?focusedCommentId=16777228#comment-16777228",
     "id": 16777228,
     "creationDate": 1471926091465,
     "contentType": "comment",
     "version": 1
   },
   "timestamp": 1471926091468
 }
 

Inspecting webhook contents

Each type of webhook event includes information specific to that event in the body content of the POST message. The add-on resource that listens for webhook posts should receive and process the content as appropriate for the add-on. To understand what type of content each webhook generates, you can use the Connect inspector tool.

The Connect inspector is a service that generates temporary Atlassian Connect add-on's that you can install in your development environment to inspect the content of event messages. The Connect inspector subscribes to every webhook event type available on the running instance of the Atlassian application, and prints the body posted by the instance to your web browser.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "modules": {
    "webhooks": [
      {
        "event": "jira:issue_created",
        "url": "/issue-created",
        "excludeBody": false,
        "filter": "project = HSA",
        "propertyKeys": [
          "propertyKey",
          "otherPropertyKey"
        ]
      }
    ]
  }
}

Properties

event
Type
Max length
100
Required
Yes
Description

Specifies the named event you would like to listen to (e.g., "enabled", "jira:issue_created", etc.)


url
Type
Format
uri-template
Required
Yes
Description

Specifies your add-on's POST webhook handler URL. This property must be a URL relative to the add-on's baseUrl.


conditions
Type
Description

List of conditions which must be true for the webhook to fire. Currently, we only support the addon_is_licensed condition.


excludeBody
Type
Defaults to
false
Description

Specifies if webhook will send JSON body when triggered. By default, a webhook will send a request with a JSON body.


filter
Type
Max length
10000
Description

Filter for entities that the webhook will be triggered for. Refer to the documentation on filtering for details.


key
Type
Max length
100
Pattern
^[a-zA-Z0-9-]+$
Description

A key to identify this module. Required when registering the module dynamically, otherwise ignored.


propertyKeys
Type
Description

Specifies entity properties which will be returned inside JSON body. If not specified no properties will be returned.

Currently this is supported only in Jira webhooks, for all events that support Entity Properties. Note that properties won't be returned for entity-deleted events, since the properties are already deleted by the time the webhook is sent.