A webhook is a standard mechanism for implementing HTTP callbacks. Atlassian-hosted cloud applications can execute webhooks that your add-ons can use to be notified of certain events that happen in 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

    If your add-on uses webhooks, 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 relative URL of the local resource 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.

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 ${}, a POST message will be sent to the address with the ${} replaced by the id of the project that the event was triggered for.

Webhook event types

Below is a list of all available webhook events.

Add-on and system events
  • connect_addon_disabled
  • connect_addon_enabled
  • server_upgraded
Issue events
  • jira:issue_created
  • jira:issue_deleted
  • jira:issue_updated
  • jira:worklog_updated

    Context parameters are ${}, ${project.key}, ${issue.key}, ${}

Version events
  • version_created
  • version_deleted
  • version_merged
  • version_updated
  • version_moved
  • version_released
  • version_unreleased

    Context parameters are ${}, ${project.key}, ${}.

    Special context parameter for version_merged event is ${}.

Project events
  • project_created
  • project_updated
  • project_deleted

    Context parameters are ${}, ${project.key}

User events
  • user_created
  • user_deleted
  • user_updated

    Context parameters: ${}, ${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_updated
  • attachment_viewed
  • blog_created
  • blog_removed
  • blog_restored
  • blog_trashed
  • blog_updated
  • blog_viewed
  • cache_statistics_changed
  • comment_created
  • comment_removed
  • comment_updated
  • connect_addon_disabled
  • connect_addon_enabled
  • 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
  • plugin_enabled
  • plugins_upgraded
  • search_performed
  • server_upgraded
  • space_created
  • space_logo_updated
  • space_permissions_updated
  • space_removed
  • space_updated
  • status_cleared
  • status_created
  • status_removed
  • user_created
  • user_deactivated
  • user_followed
  • user_reactivated
  • user_removed

Example Request

POST /jira-issuecreated?userid=admin&userkey=admin HTTP/1.1
Authorization: JWT ...
Atlassian-Connect-Version: x.x
Content-Type: application/json
  timestamp: 1426661049725,
  webhookEvent: 'jira:issuecreated',

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 webhook inspector tool.

The Webhook Inspector is a atlassian-connect-express Connect add-on that you can install in your development environment to inspect the content of event messages. The Webhook Inspector subscribes and generates each webhook event type available on the running instance of the Atlassian application, and prints the body posted by the instance to the console screen.



  "modules": {
    "webhooks": [
        "event": "jira:issue_created",
        "url": "/issue-created"




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




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



This object represents a map of key/value pairs, where each property name and value corresponds to the parameter name and value respectively.


  "params": {
    "someOtherProperty": "someValue",
    "myCustomProperty": "myValue"