A webhook is a user-defined callback over HTTPS. You can use Jira webhooks to notify your app or web application when certain events occur in Jira. For example, you might want to alert your remote application when an issue has been updated or when sprint has been started. Using a webhook to do this means that your remote application doesn't have to periodically poll Jira (via the REST APIs) to determine whether changes have occurred.
A webhook in Jira is defined by the following information, which you need to provide when registering (i.e. creating) a new webhook:
("project = TEST and fixVersion = future")To register (i.e. create) a webhook, you can use any of the following methods:
sharedSecret)The information in this section will help you configure a webhook, whether you are creating a new one or modifying an existing one.
The following events are available for Jira webhooks. The string in parentheses is the name of the webhookEvent in the response.
If you only want your webhook events to fire for a specific set of issues, you can specify a JQL query in your webhook to send only events triggered by matching issues. For example, you could register for all Issue Deleted events on issues in the Test ("TEST") Project with the Performance component.
JQL filtering is only supported by a subset of webhook events. Refer to the event sections below for details.
Note, although the JQL that uses standard Jira fields is very performant, some custom fields, because of their implementation, can take multiple seconds to query. You should take this into account when using JQL for a webhook, as the query will be run with each event.
jira:issue_created)jira:issue_updated)jira:issue_deleted)JQL filtering supported.
worklog_created)worklog_updated)worklog_deleted)Note, callbacks for worklog events will soon be restricted to only include the 100 most recent items. See the notice.
comment_created)comment_updated)comment_deleted)JQL filtering supported.
attachment_created)attachment_deleted)issuelink_created)issuelink_deleted)project_created)project_updated)project_deleted)jira:version_released)jira:version_unreleased)jira:version_created)jira:version_moved)jira:version_updated)jira:version_deleted)jira:version_deleted)
note, this is the same webhook event name as the 'deleted' event, but the response will include a mergedTo property*user_created)user_updated)user_deleted)option_voting_changed)option_watching_changed*)option_unassigned_issues_changed)option_subtasks_changed)option_attachments_changed)option_issuelinks_changed)option_timetracking_changed)sprint_created)sprint_deleted)sprint_updated)sprint_started)sprint_closed)board_created)board_updated)board_deleted)board_configuration_changed)If you are unsure which events to register your webhook for, then the simplest approach is to register your webhook for all events for the relevant entity (e.g. all issue-related events). Then you won't need to update the webhook if you need to handle these events in future; you can just add code in your app or web application once you want to react to them.
You can append variables to the webhook URL when creating or updating a webhook. The variables are listed below:
${board.id}${issue.id}${issue.key}${mergedVersion.id}${modifiedUser.accountId}${project.id}${project.key}${sprint.id}${version.id}You can use these variables to dynamically insert the value of the current issue key, sprint ID, project key, etc, into the webhook URL when it is triggered. Consider the following example:
Say you specified the URL for your webhook with the ${issue.key} variable, like this:
1
https://service.example.com/webhook/${issue.key}If an issue with the key EXA-1 triggers a webhook, then the URL that will be used is:
1
https://service.example.com/webhook/EXA-1If the URL you have defined does not return a successful response to the webhook POST, Jira Cloud will retry sending three times. Currently there is no backoff or log available. If you are concerned about missed webhooks, we recommend occasionally polling Jira for recent updates.
This API allows Connect apps to register webhooks with JQL filters. This is a more flexible alternative to declaring webhooks statically in the app descriptor.
We want to provide a performant experience for apps and their users. This is why the following limitations apply to this API:
jira:issue_created, jira:issue_updated, jira:issue_deleted, comment_created, comment_updated, comment_deleted.issueKey, project, issuetype, status, assignee, reporter, issue.property, cf[id] (for custom fields).=, !=, IN, and NOT IN.If you would like more clauses or operators to be supported, raise a request in the Atlassian Connect in Jira project or vote for a relevant issue there.
Important: While this is not the case now, in the future we may require apps to periodically ping Jira to renew registered webhooks, or they will be deleted automatically.
To register webhooks through the REST API, make a POST request to https://your-domain.atlassian.net/rest/api/2/webhook. An example request body is shown below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
{
"url": "https://your-app-base-url.com/webhook-received",
"webhooks": [
{
"jqlFilter": "project = PRJ AND status = Done",
"events": ["jira:issue_created", "jira:issue_updated"]
},
{
"jqlFilter": "status = Done",
"events": ["jira:issue_updated"]
},
{
"jqlFilter": "unsupportedClause = something",
"events": ["jira:issue_deleted"]
}
]
}This request will try to register three webhooks. The response will be a JSON array with a result for every webhook. In this case, we will likely succeed in registering the first two, while the third one will fail due to the unsupported JQL clause. The response will then look like this:
1 2 3 4 5
[
{"createdWebhookId": 1000},
{"createdWebhookId": 1001},
{"errors": ["The clause unsupportedClause is unsupported"]}
]To fetch webhooks registered through the REST API, make a GET request to https://your-domain.atlassian.net/rest/api/2/webhook.
This API uses pagination. The query parameters startAt and maxResults can be provided to specify the desired page, or the default values of 0 and 100 will be used.
To delete webhooks registered through this REST API, a DELETE request can be made to https://your-domain.atlassian.net/rest/api/2/webhook.
In your request, include the IDs of the webhooks to be deleted:
1 2 3
{
"webhookIds": [1000, 1001]
}IDs corresponding to non-existent webhooks are ignored.
The format is the same as for webhooks declared in the Connect app descriptor, but with an additional property specifying which webhooks were matched for the event.
For example, if an event happens in Jira that matches both JQL filters of the webhooks registered, which were successfully registered and assigned the IDs of 1000 and 1001, the webhook data JSON will contain the additional matchedWebhookIds root level property:
1 2 3 4
{
... usual webhook data ...,
"matchedWebhookIds": [1000, 1001]
}An example Connect app that uses the new REST API to register webhooks, fetch registered webhooks, delete them, and handle them, can be found here.
To register a webhook via REST:
POST a webhook in JSON format to:
https://your-domain.atlassian.net/rest/webhooks/1.0/webhook
1 2 3 4 5 6 7 8 9 10
{
"name": "my first webhook via rest",
"url": "https://www.example.com/webhooks",
"events": [
"jira:issue_created",
"jira:issue_updated"
],
"jqlFilter": "Project = JRA AND resolution = Fixed",
"excludeIssueDetails" : false
}The response will return the webhook in JSON with additional information, including the user that created the webhook, the created timestamp, etc.
To unregister (i.e. delete) a webhook via REST:
Execute a DELETE to the following URL:
https://your-domain.atlassian.net/rest/webhooks/1.0/webhook/{webhookId}
The following would delete the webhook with an ID of 70:
1 2 3 4
curl --user username:password \
-X DELETE \
-H "Content-Type: application/json" \
https://your-domain.atlassian.net/rest/webhooks/1.0/webhook/70To query a webhook via REST:
To get all webhooks for a Jira instance, perform a GET with the following URL:
https://your-domain.atlassian.net/rest/webhooks/1.0/webhook.
1 2 3 4
curl --user username:password \
-X GET \
-H "Content-Type: application/json" \
https://your-domain.atlassian.net/rest/webhooks/1.0/webhookTo get a specific webhook by its ID, perform a GET with the following URL:
https://your-domain.atlassian.net/rest/webhooks/1.0/webhook/{webhookId}
The following would get a webhook with an ID of 72:
1 2 3 4
curl --user username:password \
-X GET \
-H "Content-Type: application/json" \
https://your-domain.atlassian.net/rest/webhooks/1.0/webhook/72Webhooks can be attached as a workflow post function. This makes it easy to trigger a webhook when an issue makes a workflow transition, for instance when it gets rejected from QA or when it gets resolved.
To add a webhook as a post function to a workflow:
Notes:
Webhooks will be run without a specific user context, e.g. all issues will be available to the webhook, rather than having them scoped to a single user. (Note the URL will also contain user parameters in the form ?user_id=admin&user_key=admin appended at the end.)
By default, a webhook will send a request with a JSON callback when it is triggered. If you don't want the JSON body sent, then you will need to select Exclude body when configuring the webhook.
At a high level, every callback contains the webhookEvent ID, the timestamp, and information about the entity associated with the event (e.g. issue, project, board, etc). Callbacks may have additional information, depending on the type of event associated with it. As an example, the structure of a callback for an issue-related event is described below:
A callback for an issue-related event is structured like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
{
"timestamp",
"event",
"user": {
--> See User shape in table below
},
"issue": {
--> See Issue shape in table below
},
"changelog" : {
--> See Changelog shape in table below
},
"comment" : {
--> See Comment shape in table below
}
}| Issue shape |
|
| User shape |
|
accountType field that is used to distinguish different types of users, such as normal users (atlassian), app users (app), and Jira Service Desk customers (customer).This is similar in format to the changelog you would retrieve from a Jira issue, but without the user (since that is already in the JSON) and without the created timestamp (since that is also already in the JSON for a webhook event)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
{
"changelog": {
"items": [
{
"toString": "A new summary.",
"to": null,
"fromString": "What is going on here?????",
"from": null,
"fieldtype": "jira",
"field": "summary"
},
{
"toString": "New Feature",
"to": "2",
"fromString": "Improvement",
"from": "4",
"fieldtype": "jira",
"field": "issuetype"
},
],
"id": 10124
}
}You can see a full example of this below. This JSON callback shows an update to an issue (some fields changed value) where a comment was also added:
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 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
{
"id": 2,
"timestamp": "2009-09-09T00:08:36.796-0500",
"issue": {
"expand":"renderedFields,names,schema,transitions,operations,editmeta,changelog",
"id":"99291",
"self":"https://jira.atlassian.com/rest/api/2/issue/99291",
"key":"JRA-20002",
"fields":{
"summary":"I feel the need for speed",
"created":"2009-12-16T23:46:10.612-0600",
"description":"Make the issue nav load 10x faster",
"labels":["UI", "dialogue", "move"],
"priority": "Minor"
}
},
"user": {
"self":"https://jira.atlassian.com/rest/api/2/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
"accoundId": "99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
"name":"brollins",
"emailAddress":"bryansemail at atlassian dot com",
"avatarUrls":{
"16x16":"https://jira.atlassian.com/secure/useravatar?size=small&avatarId=10605",
"48x48":"https://jira.atlassian.com/secure/useravatar?avatarId=10605"
},
"displayName":"Bryan Rollins [Atlassian]",
"active" : "true"
},
"changelog": {
"items": [
{
"toString": "A new summary.",
"to": null,
"fromString": "What is going on here?????",
"from": null,
"fieldtype": "jira",
"field": "summary"
},
{
"toString": "New Feature",
"to": "2",
"fromString": "Improvement",
"from": "4",
"fieldtype": "jira",
"field": "issuetype"
}
],
"id": 10124
},
"comment" : {
"self":"https://jira.atlassian.com/rest/api/2/issue/10148/comment/252789",
"id":"252789",
"author":{
"self":"https://jira.atlassian.com/rest/api/2/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
"name":"brollins",
"accountId": "99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
"emailAddress":"bryansemail@atlassian.com",
"avatarUrls":{
"16x16":"https://jira.atlassian.com/secure/useravatar?size=small&avatarId=10605",
"48x48":"https://jira.atlassian.com/secure/useravatar?avatarId=10605"
},
"displayName":"Bryan Rollins [Atlassian]",
"active":true
},
"body":"Just in time for AtlasCamp!",
"updateAuthor":{
"self":"https://jira.atlassian.com/rest/api/2/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
"accoundId": "99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
"name":"brollins",
"emailAddress":"brollins@atlassian.com",
"avatarUrls":{
"16x16":"https://jira.atlassian.com/secure/useravatar?size=small&avatarId=10605",
"48x48":"https://jira.atlassian.com/secure/useravatar?avatarId=10605"
},
"displayName":"Bryan Rollins [Atlassian]",
"active":true
},
"created":"2011-06-07T10:31:26.805-0500",
"updated":"2011-06-07T10:31:26.805-0500"
},
"timestamp": "2011-06-07T10:31:26.805-0500",
"webhookEvent": "jira:issue_updated"
}If a webhook is triggered successfully, a response code of 200 is returned. All other response codes should be treated as an unsuccessful attempt to trigger the webhook.
issue_created event instead.