Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
contact:
email: ecosystem@atlassian.com
description: Jira Cloud platform REST API documentation
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
title: Jira Cloud platform REST Webhooks API
version: 1001.0.0-SNAPSHOT-82b018affa468e58f284fbe4df33536469d757df
servers:
- url: https://your-domain.atlassian.net
tags:
- description: This resource represents webhooks. Webhooks are calls sent to a URL when an event occurs in Jira for issues specified by a JQL query. Only Connect and OAuth 2.0 apps can register and manage webhooks. For more information, see Webhooks.
name: Webhooks
paths:
/rest/api/3/webhook:
delete:
deprecated: false
description: 'Removes webhooks by ID. Only webhooks registered by the calling app are removed. If webhooks created by other apps are specified, they are ignored.
**Permissions required:** Only Connect and OAuth 2.0 apps can use this operation.'
operationId: deleteWebhookById
parameters: []
requestBody:
content:
application/json:
example:
webhookIds:
- 10000
- 10001
- 10042
schema:
$ref: '#/components/schemas/ContainerForWebhookIDs'
required: true
responses:
'202':
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the list of webhook IDs is missing.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the caller isn't an app.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- manage:jira-webhook
summary: Delete webhooks by ID
tags:
- Webhooks
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
- manage:jira-webhook
state: Current
- scheme: OAuth2
scopes:
- delete:webhook:jira
state: Beta
x-atlassian-connect-scope: READ
get:
deprecated: false
description: 'Returns a paginated list of the webhooks registered by the calling app.
**Permissions required:** Only Connect and OAuth 2.0 apps can use this operation.'
operationId: getDynamicWebhooksForApp
parameters:
- description: The index of the first item to return in a page of results (page offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 100
format: int32
type: integer
responses:
'200':
content:
application/json:
example: '{"isLast":true,"maxResults":3,"startAt":0,"total":3,"values":[{"events":["jira:issue_updated","jira:issue_created"],"expirationDate":"2019-06-01T12:42:30.000+0000","fieldIdsFilter":["summary","customfield_10029"],"id":10000,"jqlFilter":"project = PRJ","url":"https://your-app.example.com/webhook-received"},{"events":["jira:issue_created"],"expirationDate":"2019-06-01T12:42:30.000+0000","id":10001,"jqlFilter":"issuetype = Bug","url":"https://your-app.example.com/webhook-received"},{"events":["issue_property_set"],"expirationDate":"2019-06-01T12:42:30.000+0000","id":10002,"issuePropertyKeysFilter":["my-issue-property-key"],"jqlFilter":"project = PRJ","url":"https://your-app.example.com/webhook-received"}]}'
schema:
$ref: '#/components/schemas/PageBeanWebhook'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the caller isn't an app.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- manage:jira-webhook
summary: Get dynamic webhooks for app
tags:
- Webhooks
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
- manage:jira-webhook
state: Current
- scheme: OAuth2
scopes:
- read:webhook:jira
- read:jql:jira
state: Beta
x-atlassian-connect-scope: READ
post:
deprecated: false
description: 'Registers webhooks.
**NOTE:** for non-public OAuth apps, webhooks are delivered only if there is a match between the app owner and the user who registered a dynamic webhook.
**Permissions required:** Only Connect and OAuth 2.0 apps can use this operation.'
operationId: registerDynamicWebhooks
parameters: []
requestBody:
content:
application/json:
example:
url: https://your-app.example.com/webhook-received
webhooks:
- events:
- jira:issue_created
- jira:issue_updated
fieldIdsFilter:
- summary
- customfield_10029
jqlFilter: project = PROJ
- events:
- jira:issue_deleted
jqlFilter: project IN (PROJ, EXP) AND status = done
- events:
- issue_property_set
issuePropertyKeysFilter:
- my-issue-property-key
jqlFilter: project = PROJ
schema:
$ref: '#/components/schemas/WebhookRegistrationDetails'
required: true
responses:
'200':
content:
application/json:
example: '{"webhookRegistrationResult":[{"createdWebhookId":1000},{"errors":["The clause watchCount is unsupported"]},{"createdWebhookId":1001}]}'
schema:
$ref: '#/components/schemas/ContainerForRegisteredWebhooks'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the caller isn't an app.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- manage:jira-webhook
summary: Register dynamic webhooks
tags:
- Webhooks
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
- manage:jira-webhook
state: Current
- scheme: OAuth2
scopes:
- read:field:jira
- read:project:jira
- write:webhook:jira
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/webhook/failed:
get:
deprecated: false
description: 'Returns webhooks that have recently failed to be delivered to the requesting app after the maximum number of retries.
After 72 hours the failure may no longer be returned by this operation.
The oldest failure is returned first.
This method uses a cursor-based pagination. To request the next page use the failure time of the last webhook on the list as the `failedAfter` value or use the URL provided in `next`.
**Permissions required:** Only Connect apps can use this operation.'
operationId: getFailedWebhooks
parameters:
- description: The maximum number of webhooks to return per page. If obeying the maxResults directive would result in records with the same failure time being split across pages, the directive is ignored and all records with the same failure time included on the page.
in: query
name: maxResults
schema:
format: int32
type: integer
- description: The time after which any webhook failure must have occurred for the record to be returned, expressed as milliseconds since the UNIX epoch.
in: query
name: after
schema:
format: int64
type: integer
responses:
'200':
content:
application/json:
example: '{"values":[{"id":"1","body":"{\"data\":\"webhook data\"}","url":"https://example.com","failureTime":1573118132000},{"id":"2","url":"https://example.com","failureTime":1573540473480}],"maxResults":100,"next":"https://your-domain.atlassian.net/rest/api/3/webhook/failed?failedAfter=1573540473480&maxResults=100"}'
schema:
$ref: '#/components/schemas/FailedWebhooks'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: 400 response
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the caller is not a Connect app.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- manage:jira-webhook
summary: Get failed webhooks
tags:
- Webhooks
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
- manage:jira-webhook
state: Current
- scheme: OAuth2
scopes:
- read:issue-details:jira
- read:webhook:jira
- read:comment.property:jira
- read:group:jira
- read:issue-type:jira
- read:project-role:jira
- read:epic:jira-software
state: Beta
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/webhook/refresh:
put:
deprecated: false
description: 'Extends the life of webhook. Webhooks registered through the REST API expire after 30 days. Call this operation to keep them alive.
Unrecognized webhook IDs (those that are not found or belong to other apps) are ignored.
**Permissions required:** Only Connect and OAuth 2.0 apps can use this operation.'
operationId: refreshWebhooks
parameters: []
requestBody:
content:
application/json:
example:
webhookIds:
- 10000
- 10001
- 10042
schema:
$ref: '#/components/schemas/ContainerForWebhookIDs'
required: true
responses:
'200':
content:
application/json:
example: '{"expirationDate":"2019-06-01T12:42:30.000+0000"}'
schema:
$ref: '#/components/schemas/WebhooksExpirationDate'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the caller isn't an app.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- manage:jira-webhook
summary: Extend webhook life
tags:
- Webhooks
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
- manage:jira-webhook
state: Current
- scheme: OAuth2
scopes:
- write:webhook:jira
- read:webhook:jira
state: Beta
x-atlassian-connect-scope: READ
components:
schemas:
ErrorCollection:
additionalProperties: false
description: Error messages from an operation.
properties:
errorMessages:
description: The list of error messages produced by this operation. For example, "input parameter 'key' must be provided"
items:
type: string
type: array
errors:
additionalProperties:
type: string
description: 'The list of errors by parameter returned by the operation. For example,"projectKey": "Project keys must start with an uppercase letter, followed by one or more uppercase alphanumeric characters."'
type: object
status:
format: int32
type: integer
type: object
RegisteredWebhook:
additionalProperties: false
description: ID of a registered webhook or error messages explaining why a webhook wasn't registered.
properties:
createdWebhookId:
description: The ID of the webhook. Returned if the webhook is created.
format: int64
type: integer
errors:
description: Error messages specifying why the webhook creation failed.
items:
description: Error messages specifying why the webhook creation failed.
type: string
type: array
type: object
ContainerForWebhookIDs:
additionalProperties: false
description: Container for a list of webhook IDs.
properties:
webhookIds:
description: A list of webhook IDs.
items:
description: A list of webhook IDs.
format: int64
type: integer
type: array
required:
- webhookIds
type: object
WebhooksExpirationDate:
additionalProperties: false
description: The date the refreshed webhooks expire.
properties:
expirationDate:
description: The expiration date of all the refreshed webhooks.
format: int64
readOnly: true
type: integer
required:
- expirationDate
type: object
WebhookRegistrationDetails:
additionalProperties: false
description: Details of webhooks to register.
properties:
url:
description: The URL that specifies where to send the webhooks. This URL must use the same base URL as the Connect app. Only a single URL per app is allowed to be registered.
type: string
webhooks:
description: A list of webhooks.
items:
$ref: '#/components/schemas/WebhookDetails'
type: array
required:
- url
- webhooks
type: object
PageBeanWebhook:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/Webhook'
readOnly: true
type: array
type: object
WebhookDetails:
additionalProperties: false
description: A list of webhooks.
properties:
events:
description: The Jira events that trigger the webhook.
items:
enum:
- jira:issue_created
- jira:issue_updated
- jira:issue_deleted
- comment_created
- comment_updated
- comment_deleted
- issue_property_set
- issue_property_deleted
- sprint_created
- sprint_updated
- sprint_closed
- sprint_deleted
- sprint_started
- jira:version_released
- jira:version_unreleased
- jira:version_created
- jira:version_moved
- jira:version_updated
- jira:version_merged
- jira:version_deleted
type: string
type: array
fieldIdsFilter:
description: A list of field IDs. When the issue changelog contains any of the fields, the webhook `jira:issue_updated` is sent. If this parameter is not present, the app is notified about all field updates.
items:
description: A list of field IDs. When the issue changelog contains any of the fields, the webhook <code>jira:issue_updated</code> is sent. If this parameter is not present, the app is notified about all field updates.
type: string
type: array
issuePropertyKeysFilter:
description: A list of issue property keys. A change of those issue properties triggers the `issue_property_set` or `issue_property_deleted` webhooks. If this parameter is not present, the app is notified about all issue property updates.
items:
description: A list of issue property keys. A change of those issue properties triggers the <code>issue_property_set</code> or <code>issue_property_deleted</code> webhooks. If this parameter is not present, the app is notified about all issue property updates.
type: string
type: array
jqlFilter:
description: "The JQL filter that specifies which issues the webhook is sent for. Only a subset of JQL can be used. The supported elements are:\n\n * Fields: `issueKey`, `project`, `issuetype`, `status`, `assignee`, `reporter`, `issue.property`, and `cf[id]`. For custom fields (`cf[id]`), only the epic label custom field is supported.\".\n * Operators: `=`, `!=`, `IN`, and `NOT IN`."
type: string
required:
- events
- jqlFilter
type: object
ContainerForRegisteredWebhooks:
additionalProperties: false
description: Container for a list of registered webhooks. Webhook details are returned in the same order as the request.
properties:
webhookRegistrationResult:
description: A list of registered webhooks.
items:
$ref: '#/components/schemas/RegisteredWebhook'
type: array
type: object
FailedWebhook:
additionalProperties: false
description: Details about a failed webhook.
properties:
body:
description: The webhook body.
type: string
failureTime:
description: The time the webhook was added to the list of failed webhooks (that is, the time of the last failed retry).
format: int64
type: integer
id:
description: The webhook ID, as sent in the `X-Atlassian-Webhook-Identifier` header with the webhook.
type: string
url:
description: The original webhook destination.
type: string
required:
- failureTime
- id
- url
type: object
Webhook:
additionalProperties: false
description: A webhook.
properties:
events:
description: The Jira events that trigger the webhook.
items:
enum:
- jira:issue_created
- jira:issue_updated
- jira:issue_deleted
- comment_created
- comment_updated
- comment_deleted
- issue_property_set
- issue_property_deleted
- sprint_created
- sprint_updated
- sprint_closed
- sprint_deleted
- sprint_started
- jira:version_released
- jira:version_unreleased
- jira:version_created
- jira:version_moved
- jira:version_updated
- jira:version_merged
- jira:version_deleted
type: string
type: array
expirationDate:
description: The date after which the webhook is no longer sent. Use [Extend webhook life](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-webhooks/#api-rest-api-3-webhook-refresh-put) to extend the date.
format: int64
readOnly: true
type: integer
fieldIdsFilter:
description: A list of field IDs. When the issue changelog contains any of the fields, the webhook `jira:issue_updated` is sent. If this parameter is not present, the app is notified about all field updates.
items:
description: A list of field IDs. When the issue changelog contains any of the fields, the webhook <code>jira:issue_updated</code> is sent. If this parameter is not present, the app is notified about all field updates.
type: string
type: array
id:
description: The ID of the webhook.
format: int64
type: integer
issuePropertyKeysFilter:
description: A list of issue property keys. A change of those issue properties triggers the `issue_property_set` or `issue_property_deleted` webhooks. If this parameter is not present, the app is notified about all issue property updates.
items:
description: A list of issue property keys. A change of those issue properties triggers the <code>issue_property_set</code> or <code>issue_property_deleted</code> webhooks. If this parameter is not present, the app is notified about all issue property updates.
type: string
type: array
jqlFilter:
description: The JQL filter that specifies which issues the webhook is sent for.
type: string
url:
description: The URL that specifies where the webhooks are sent.
type: string
required:
- events
- id
- jqlFilter
- url
type: object
FailedWebhooks:
additionalProperties: false
description: A page of failed webhooks.
properties:
maxResults:
description: The maximum number of items on the page. If the list of values is shorter than this number, then there are no more pages.
format: int32
type: integer
next:
description: The URL to the next page of results. Present only if the request returned at least one result.The next page may be empty at the time of receiving the response, but new failed webhooks may appear in time. You can save the URL to the next page and query for new results periodically (for example, every hour).
format: uri
type: string
values:
description: The list of webhooks.
items:
$ref: '#/components/schemas/FailedWebhook'
type: array
required:
- maxResults
- values
type: object
securitySchemes:
OAuth2:
description: OAuth2 scopes for Jira
flows:
authorizationCode:
authorizationUrl: https://auth.atlassian.com/authorize
scopes:
delete:async-task:jira: Delete asynchronous task.
delete:attachment:jira: Delete issue attachments.
delete:avatar:jira: Delete system and custom avatars.
delete:comment.property:jira: Delete issue comment properties.
delete:comment:jira: Delete issue comments.
delete:dashboard.property:jira: Delete dashboard properties.
delete:dashboard:jira: Delete dashboards.
delete:field-configuration-scheme:jira: Delete field configuration schemes.
delete:field-configuration:jira: Delete field configurations.
delete:field.option:jira: Delete field options.
delete:field:jira: Delete fields.
delete:filter.column:jira: Delete filter columns.
delete:filter:jira: Delete filters.
delete:group:jira: Delete user groups.
delete:issue-link-type:jira: Delete issue link types.
delete:issue-link:jira: Delete issue links.
delete:issue-type-scheme:jira: Delete issue type schemes.
delete:issue-type-screen-scheme:jira: Delete issue type screen schemes.
delete:issue-type.property:jira: Delete issue type properties.
delete:issue-type:jira: Delete issue types.
delete:issue-worklog.property:jira: Delete issue worklog properties.
delete:issue-worklog:jira: Delete issue worklogs.
delete:issue.property:jira: Delete issue properties.
delete:issue.remote-link:jira: Delete issue remote links.
delete:issue:jira: Delete issues.
delete:permission-scheme:jira: Delete permission schemes.
delete:permission:jira: Delete permissions.
delete:project-category:jira: Delete project categories.
delete:project-role:jira: Delete project roles.
delete:project-version:jira: Delete project versions.
delete:project.avatar:jira: Delete project avatars.
delete:project.component:jira: Delete project components.
delete:project.property:jira: Delete project properties.
delete:project:jira: Delete projects and their details, such as issue types, project lead, and avatars.
delete:screen-scheme:jira: Delete screen schemes.
delete:screen-tab:jira: Delete screen tabs.
delete:screen:jira: Delete screens.
delete:screenable-field:jira: Delete screenable fields.
delete:user-configuration:jira: Delete user configurations.
delete:user.property:jira: Delete user properties.
delete:webhook:jira: Delete webhooks.
delete:workflow-scheme:jira: Delete workflow schemes.
delete:workflow.property:jira: Delete workflow properties.
delete:workflow:jira: Delete workflows.
manage:jira-configuration: Configure Jira settings that require the Jira administrators permission, for example, create projects and custom fields, view workflows, manage issue link types.
manage:jira-project: Create and edit project settings and create new project-level objects, for example, versions, components.
manage:jira-webhook: Manage Jira webhooks. Enables an OAuth app to register and unregister dynamic webhooks in Jira. It also provides for fetching of registered webhooks.
read:app-data:jira: Read app data.
read:application-role:jira: View application roles.
read:attachment:jira: View issue attachments.
read:audit-log:jira: View audit logs.
read:avatar:jira: View system and custom avatars.
read:comment.property:jira: View issue comment properties.
read:comment:jira: View issue comments.
read:custom-field-contextual-configuration:jira: Read custom field contextual configurations.
read:dashboard.property:jira: View dashboard properties.
read:dashboard:jira: View dashboards.
read:email-address:jira: View email addresses of all users regardless of the user's profile visibility settings.
read:field-configuration-scheme:jira: View field configuration schemes.
read:field-configuration:jira: Read field configurations.
read:field.default-value:jira: View field default values.
read:field.option:jira: View field options.
read:field.options:jira: Read field options.
read:field:jira: View fields.
read:filter.column:jira: View filter columns.
read:filter.default-share-scope:jira: View filter default share scopes.
read:filter:jira: View filters.
read:group:jira: View user groups.
read:instance-configuration:jira: View instance configurations.
read:issue-details:jira: View issue details.
read:issue-event:jira: Read issue events.
read:issue-field-values:jira: View issue field valueses.
read:issue-link-type:jira: View issue link types.
read:issue-link:jira: View issue links.
read:issue-meta:jira: View issue meta.
read:issue-security-level:jira: View issue security levels.
read:issue-security-scheme:jira: View issue security schemes.
read:issue-status:jira: View issue statuses.
read:issue-type-hierarchy:jira: Read issue type hierarchies.
read:issue-type-scheme:jira: View issue type schemes.
read:issue-type-screen-scheme:jira: View issue type screen schemes.
read:issue-type.property:jira: View issue type properties.
read:issue-type:jira: View issue types.
read:issue-worklog.property:jira: View issue worklog properties.
read:issue-worklog:jira: View issue worklogs.
read:issue.changelog:jira: View issue changelogs.
read:issue.property:jira: View issue properties.
read:issue.remote-link:jira: View issue remote links.
read:issue.time-tracking:jira: View issue time trackings.
read:issue.transition:jira: View issue transitions.
read:issue.vote:jira: View issue votes.
read:issue.votes:jira: View issue voteses.
read:issue.watcher:jira: View issue watchers.
read:issue:jira: View issues.
read:jira-expressions:jira: View jira expressions.
read:jira-user: View user information in Jira that you have access to, including usernames, email addresses, and avatars.
read:jira-work: Read project and issue data. Search for issues and objects associated with issues (such as attachments and worklogs).
read:jql:jira: View JQL.
read:label:jira: View labels.
read:license:jira: View licenses.
read:notification-scheme:jira: View notification schemes.
read:permission-scheme:jira: View permission schemes.
read:permission:jira: View permissions.
read:priority:jira: View priorities.
read:project-category:jira: View project categories.
read:project-role:jira: View project roles.
read:project-type:jira: View project types.
read:project-version:jira: View project versions.
read:project.avatar:jira: Read project avatars.
read:project.component:jira: View project components.
read:project.email:jira: View project emails.
read:project.feature:jira: Read project features.
read:project.property:jira: View project properties.
read:project:jira: View projects.
read:resolution:jira: View resolutions.
read:role:jira: View roles.
read:screen-field:jira: View screen fields.
read:screen-scheme:jira: View screen schemes.
read:screen-tab:jira: View screen tabs.
read:screen:jira: View screens.
read:screenable-field:jira: View screenable fields.
read:status:jira: View statuses.
read:user-configuration:jira: View user configurations.
read:user.columns:jira: View user columnses.
read:user.property:jira: View user properties.
read:user:jira: View users.
read:webhook:jira: View webhooks.
read:workflow-scheme:jira: Vie
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jira/refs/heads/main/openapi/jira-webhooks-api-openapi.yml