Class WebhooksService

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.

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-webhooks

Hierarchy

  • CommonHttpService
    • WebhooksService

Constructors

constructor

Methods

deleteWebhookById getDynamicWebhooksForApp getFailedWebhooks refreshWebhooks registerDynamicWebhooks initialize

Constructors

constructor

  • new WebhooksService(getClientInstance): WebhooksService
  • Internal

    Create a new instance of the service.

    Parameters

    • getClientInstance: (() => CommonHttpClient)
        • (): CommonHttpClient

        • Returns CommonHttpClient

    Returns WebhooksService

Methods

deleteWebhookById

getDynamicWebhooksForApp

  • getDynamicWebhooksForApp(params?): Promise<PageBeanWebhook>

  • 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.

    Parameters

    • params: {
          maxResults?: number;
          startAt?: number;
      } = {}
      • OptionalmaxResults?: number

        The maximum number of items to return per page.

      • OptionalstartAt?: number

        The index of the first item to return in a page of results (page offset).

    Returns Promise<PageBeanWebhook>

    Returned if the request is successful.

    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"
        }
      ]
    }

    Path

    GET /rest/api/3/webhook @scopes-current read:jira-work, manage:jira-webhook @scopes-beta read:webhook:jira, read:jql:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-webhooks#api-rest-api-3-webhook-get

getFailedWebhooks

  • getFailedWebhooks(params?): Promise<FailedWebhooks>

  • 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.

    Parameters

    • params: {
          after?: number;
          maxResults?: number;
      } = {}
      • Optionalafter?: number

        The time after which any webhook failure must have occurred for the record to be returned, expressed as milliseconds since the UNIX epoch.

      • OptionalmaxResults?: number

        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.

    Returns Promise<FailedWebhooks>

    Returned if the request is successful.

    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"
    }

    Path

    GET /rest/api/3/webhook/failed @scopes-current read:jira-work, manage:jira-webhook @scopes-beta 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

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-webhooks#api-rest-api-3-webhook-failed-get

refreshWebhooks

registerDynamicWebhooks

  • registerDynamicWebhooks(params): Promise<ContainerForRegisteredWebhooks>

  • 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.

    Parameters

    • params: {
          webhookRegistrationDetails: WebhookRegistrationDetails;
      }
      • webhookRegistrationDetails: WebhookRegistrationDetails

        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"
            }
          ]
        }

    Returns Promise<ContainerForRegisteredWebhooks>

    Returned if the request is successful.

    example:

    {
      "webhookRegistrationResult": [
        {
          "createdWebhookId": 1000
        },
        {
          "errors": [
            "The clause watchCount is unsupported"
          ]
        },
        {
          "createdWebhookId": 1001
        }
      ]
    }

    Path

    POST /rest/api/3/webhook @scopes-current read:jira-work, manage:jira-webhook @scopes-beta read:field:jira, read:project:jira, write:webhook:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-webhooks#api-rest-api-3-webhook-post

Protected Staticinitialize

  • initialize(): void

  • Method to initialize the class. Normally used to set up validation rules.

    Returns void

Settings

Member Visibility

On This Page

Constructors
Methods