• Announcement banner
  • App data policies (EAP)
  • Application roles
  • Audit records
  • Avatars
  • Classification levels
  • Dashboards
  • Filters
  • Filter sharing
  • Group and user picker
  • Groups
  • Issues
  • UI modifications (apps)
  • Issue attachments
  • Issue comments
  • Issue comment properties
  • Issue fields
  • Issue field configurations
  • Issue custom field contexts
  • Issue custom field options
  • Issue custom field options (apps)
  • Issue custom field values (apps)
  • Issue custom field configuration (apps)
  • Issue navigator settings
  • Issue notification schemes
  • Issue priorities
  • Issue properties
  • Issue resolutions
  • Issue security level
  • Issue security schemes
  • Issue types
  • Issue type schemes
  • Issue type screen schemes
  • Issue type properties
  • Issue votes
  • Issue watchers
  • Issue worklogs
  • Issue worklog properties
  • Jira expressions
  • Jira settings
  • JQL
  • JQL functions (apps)
  • Labels
  • License metrics
  • Myself
  • Permissions
  • Permission schemes
  • Projects
  • Project avatars
  • Project categories
  • Project classification levels
  • Project components
  • Project email
  • Project features
  • Project key and name validation
  • Project permission schemes
  • Project properties
  • Project roles
  • Project role actors
  • Project types
  • Project versions
  • Screens
  • Screen tabs
  • Screen tab fields
  • Screen schemes
  • Server info
  • Status
  • Tasks
  • Time tracking
  • Users
  • User properties
  • Webhooks
  • Workflows
  • Workflow transition rules
  • Workflow schemes
  • Workflow scheme project associations
  • Workflow scheme drafts
  • Workflow statuses
  • Workflow status categories
  • Workflow transition properties
  • App properties
  • Dynamic modules
  • App migration
  • Service Registry
Cloud
Jira Cloud platform / Reference / REST API v3 (beta)

Webhooks

Postman Collection
OpenAPI

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.

GET

Get dynamic webhooks for app

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-work, manage:jira-webhook
Granular:read:webhook:jira, read:jql:jira

Request

Query parameters

startAt

integer

maxResults

integer

Responses

Returned if the request is successful.

application/json

PageBeanWebhook

A page of items.

GET/rest/api/3/webhook
1 2 3 4 5 6 7 8 9 10 11 12 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; const response = await api.asUser().requestJira(route`/rest/api/3/webhook`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
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 { "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" }, { "events": [ "jira:issue_created" ], "expirationDate": "2019-06-01T12:42:30.000+0000", "id": 10001, "jqlFilter": "issuetype = Bug" }, { "events": [ "issue_property_set" ], "expirationDate": "2019-06-01T12:42:30.000+0000", "id": 10002, "issuePropertyKeysFilter": [ "my-issue-property-key" ], "jqlFilter": "project = PRJ" } ] }
POST

Register dynamic webhooks

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-work, manage:jira-webhook
Granular:read:field:jira, read:project:jira, write:webhook:jira

Request

Request bodyapplication/json

url

string

Required
webhooks

array<WebhookDetails>

Required

Responses

Returned if the request is successful.

application/json

ContainerForRegisteredWebhooks

Container for a list of registered webhooks. Webhook details are returned in the same order as the request.

POST/rest/api/3/webhook
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 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; var bodyData = `{ "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" } ] }`; const response = await api.asUser().requestJira(route`/rest/api/3/webhook`, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: bodyData }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "webhookRegistrationResult": [ { "createdWebhookId": 1000 }, { "errors": [ "The clause watchCount is unsupported" ] }, { "createdWebhookId": 1001 } ] }
DEL

Delete webhooks by ID

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-work, manage:jira-webhook
Granular:delete:webhook:jira

Request

Request bodyapplication/json

webhookIds

array<integer>

Required

Responses

Returned if the request is successful.

DEL/rest/api/3/webhook
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; var bodyData = `{ "webhookIds": [ 10000, 10001, 10042 ] }`; const response = await api.asUser().requestJira(route`/rest/api/3/webhook`, { method: 'DELETE', headers: { 'Content-Type': 'application/json' }, body: bodyData }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.text());
GET

Get failed webhooksExperimental

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-work, manage:jira-webhook
Granular:read:issue-details:jira, read:webhook:jira, read:comment.property:jira, read:group:jira, read:issue-type:jira ...(Show more)

Request

Query parameters

maxResults

integer

after

integer

Responses

Returned if the request is successful.

application/json

FailedWebhooks

A page of failed webhooks.

GET/rest/api/3/webhook/failed
1 2 3 4 5 6 7 8 9 10 11 12 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; const response = await api.asUser().requestJira(route`/rest/api/3/webhook/failed`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "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" }
PUT

Extend webhook life

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-work, manage:jira-webhook
Granular:write:webhook:jira, read:webhook:jira

Request

Request bodyapplication/json

webhookIds

array<integer>

Required

Responses

Returned if the request is successful.

application/json

WebhooksExpirationDate

The date the refreshed webhooks expire.

PUT/rest/api/3/webhook/refresh
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; var bodyData = `{ "webhookIds": [ 10000, 10001, 10042 ] }`; const response = await api.asUser().requestJira(route`/rest/api/3/webhook/refresh`, { method: 'PUT', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: bodyData }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 { "expirationDate": "2019-06-01T12:42:30.000+0000" }

Rate this page: