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 add-on is enabled or disabled
- 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
jira:worklog\_updated
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
jira:worklog\_updated
Context parameters are ${project.id}, ${project.key}, ${issue.key}, ${issue.id}
.
Note, worklogs and comments will soon be removed from the callbacks for these events. jira:worklog_updated has also been deprecated.
See the notice.
Version events
jira:version\_created
jira:version\_deleted
jira:version\_merged
jira:version\_updated
jira:version\_moved
jira:version\_released
jira:version\_unreleased
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
Context parameters are ${project.id}, ${project.key}
User events
user\_created
user\_deleted
user\_updated
Context parameters: ${modifiedUser.name}, ${modifiedUser.key}
Feature status events
option\_voting\_changed
option\_watching\_changed
option\_unassigned\_issues\_changed
option\_subtasks\_changed
option\_attachments\_changed
option\_issuelinks\_changed
option\_timetracking\_changed
Confluence Webhook events
attachment\_created
attachment\_removed
attachment\_restored
attachment\_trashed
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\_restored
content\_trashed
content\_updated
content\_permissions\_updated
group\_created
group\_removed
label\_added
label\_created
label\_deleted
label\_removed
login
login\_failed
logout
page\_children\_reordered
page\_created
page\_moved
page\_removed
page\_restored
page\_trashed
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\_created
user\_deactivated
user\_followed
user\_reactivated
user\_removed
Example request
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:
JIRA issue-related webhook event structure
All webhook events that are sent because of JIRA issue updates will have the following structure.
{
"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
{
"page": {
"spaceKey": "~admin",
"modificationDate": 1471926079631,
"creatorKey": "ff80808154510724015451074c160001",
"creatorName": "admin",
"lastModifierKey": "ff80808154510724015451074c160001",
"self": "https://cloud-development-environment.atlassian.net/wiki/display/~admin/Some+random+test+page",
"lastModifierName": "admin",
"id": 16777227,
"title": "Some random test page",
"creationDate": 1471926079631,
"version": 1
},
"user": "admin",
"userKey": "ff80808154510724015451074c160001",
"timestamp": 1471926079645,
"username": "admin"
}
Confluence comment\_created
{
"comment": {
"spaceKey": "~admin",
"parent": {
"spaceKey": "~admin",
"modificationDate": 1471926079631,
"creatorKey": "ff80808154510724015451074c160001",
"creatorName": "admin",
"lastModifierKey": "ff80808154510724015451074c160001",
"self": "https://cloud-development-environment.atlassian.net/wiki/display/~admin/Some+random+test+page",
"lastModifierName": "admin",
"id": 16777227,
"title": "Some random test page",
"creationDate": 1471926079631,
"version": 1
},
"modificationDate": 1471926091465,
"creatorKey": "ff80808154510724015451074c160001",
"creatorName": "admin",
"lastModifierKey": "ff80808154510724015451074c160001",
"self": "https://cloud-development-environment/wiki/display/~admin/Some+random+test+page?focusedCommentId=16777228#comment-16777228",
"lastModifierName": "admin",
"id": 16777228,
"creationDate": 1471926091465,
"version": 1
},
"user": "admin",
"userKey": "ff80808154510724015451074c160001",
"timestamp": 1471926091468,
"username": "admin"
}
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