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:
If your add-on uses webhooks, you must declare the "read" scope
in your atlassian-connect.json
descriptor.
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.
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.
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
Below is a list of all available webhook events.
connect_addon_disabled
connect_addon_enabled
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
The supported context parameters are {destinationIssue.key}, {destinationIssue.id}, {destinationProject.key}, {destinationProject.id}, {sourceIssue.key}, {sourceIssue.id}, {sourceProject.key}, {sourceProject.id}
.
filter_created
filter_updated
filter_deleted
There is one supported context parameter: {filter.id}
.
issue_property_set
issue_property_deleted
The supported context parameters are {project.id}, {project.key}, {issue.key}, {issue.id}
.
issuetype_created
issuetype_updated
issuetype_deleted
The supported context parameters are {project.id}, {project.key}, {issuetype.id}
.
attachment_created
attachment_deleted
The supported context parameters are {attachment.id}
, {project.id}
, {project.key}
, {issue.key}
, {issue.id}
.
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_created
project_updated
project_deleted
The supported context parameters are {project.id}, {project.key}
project_app_enabled
project_app_disabled
The supported context parameters are {project.id}, {project.key}, {app.key}
user_created
user_deleted
user_updated
The supported context parameters are {modifiedUser.accountId}
, {modifiedUser.name}
(deprecated), {modifiedUser.key}
(deprecated)
option_voting_changed
option_watching_changed
option_unassigned_issues_changed
option_subtasks_changed
option_issuelinks_changed
option_timetracking_changed
comment_created
comment_updated
comment_deleted
The supported context parameters are {project.id}, {project.key}, {issue.key}, {issue.id}, {comment.id}
.
worklog_created
worklog_updated
worklog_deleted
The supported context parameters are {project.id}, {project.key}, {issue.key}, {issue.id}, {worklog.id}
.
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
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',
...
}
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.
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
}
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
}
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"
]
}
]
}
}
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 |
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. |
Rate this page: