Jira Cloud Webhooks

asyncapi: 2.6.0
info:
  title: Jira Cloud Webhooks
  description: >-
    Jira Cloud webhooks deliver HTTP POST payloads to a configured URL whenever
    specified events occur in your Jira instance. Webhooks can be registered
    via the Jira REST API or through the Jira administration UI. Each webhook
    delivery includes a JSON payload with details about the event, the affected
    entities, and a timestamp. Jira supports both dynamic webhooks (registered
    via REST API with expiration) and static webhooks (configured in app
    descriptors for Connect apps). Forge apps use a separate event trigger
    mechanism.
  version: '3'
  contact:
    name: Atlassian Developer Support
    url: https://developer.atlassian.com/support
    email: [email protected]
  license:
    name: Atlassian Developer Terms
    url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
  externalDocs:
    description: Jira Cloud Webhooks Documentation
    url: https://developer.atlassian.com/cloud/jira/platform/webhooks/
servers:
  webhook-receiver:
    url: '{webhookUrl}'
    protocol: https
    description: >-
      Your webhook receiver endpoint. Jira sends POST requests to this URL
      when subscribed events occur. The URL must be publicly accessible and
      respond with a 200-level status code within 10 seconds.
    variables:
      webhookUrl:
        description: The URL configured to receive Jira webhook deliveries.
channels:
  /webhook:
    description: >-
      The endpoint that receives all Jira Cloud webhook event deliveries. The
      event type is identified by the webhookEvent field in the JSON payload.
      Jira retries failed deliveries (non-200 responses) up to 8 times with
      exponential backoff.
    publish:
      operationId: receiveJiraWebhookEvent
      summary: Receive a Jira webhook event
      description: >-
        Jira delivers webhook events as HTTP POST requests with JSON payloads.
        Each delivery includes a webhookEvent field identifying the event type,
        a timestamp, and relevant entity data. The payload structure varies
        by event type but always includes the webhookEvent and timestamp
        fields.
      bindings:
        http:
          type: request
          method: POST
          headers:
            type: object
            properties:
              Content-Type:
                type: string
                enum:
                  - application/json
                description: The content type of the webhook payload.
              User-Agent:
                type: string
                description: >-
                  Identifies the request as originating from Atlassian. Typically
                  prefixed with Atlassian Webhook.
              X-Atlassian-Webhook-Identifier:
                type: string
                description: A unique identifier for the webhook configuration.
      message:
        oneOf:
          - $ref: '#/components/messages/jira:issue_created'
          - $ref: '#/components/messages/jira:issue_updated'
          - $ref: '#/components/messages/jira:issue_deleted'
          - $ref: '#/components/messages/comment_created'
          - $ref: '#/components/messages/comment_updated'
          - $ref: '#/components/messages/comment_deleted'
          - $ref: '#/components/messages/issuelink_created'
          - $ref: '#/components/messages/issuelink_deleted'
          - $ref: '#/components/messages/attachment_created'
          - $ref: '#/components/messages/attachment_deleted'
          - $ref: '#/components/messages/worklog_created'
          - $ref: '#/components/messages/worklog_updated'
          - $ref: '#/components/messages/worklog_deleted'
          - $ref: '#/components/messages/project_created'
          - $ref: '#/components/messages/project_updated'
          - $ref: '#/components/messages/project_deleted'
          - $ref: '#/components/messages/project_soft_deleted'
          - $ref: '#/components/messages/project_restored_deleted'
          - $ref: '#/components/messages/sprint_created'
          - $ref: '#/components/messages/sprint_updated'
          - $ref: '#/components/messages/sprint_deleted'
          - $ref: '#/components/messages/sprint_started'
          - $ref: '#/components/messages/sprint_closed'
          - $ref: '#/components/messages/board_created'
          - $ref: '#/components/messages/board_updated'
          - $ref: '#/components/messages/board_deleted'
          - $ref: '#/components/messages/user_created'
          - $ref: '#/components/messages/user_updated'
          - $ref: '#/components/messages/user_deleted'
          - $ref: '#/components/messages/option_voting_changed'
          - $ref: '#/components/messages/option_watching_changed'
          - $ref: '#/components/messages/option_unassigned_issues_changed'
          - $ref: '#/components/messages/option_subtasks_changed'
          - $ref: '#/components/messages/option_attachments_changed'
          - $ref: '#/components/messages/option_issuelinks_changed'
          - $ref: '#/components/messages/option_timetracking_changed'
components:
  messages:
    jira:issue_created:
      name: jira:issue_created
      title: Issue Created
      summary: Fired when a new issue is created in Jira.
      description: >-
        Triggered when a user creates a new issue. The payload includes the
        full issue details, the user who created it, and the changelog.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/IssueWebhookPayload'
      examples:
        - name: Bug created
          payload:
            timestamp: 1709478000000
            webhookEvent: jira:issue_created
            issue_event_type_name: issue_created
            user:
              accountId: 5b10a2844c20165700ede21g
              displayName: Jane Developer
              active: true
            issue:
              id: '10001'
              key: PROJ-123
              fields:
                summary: Login page returns 500 error
                issuetype:
                  name: Bug
                project:
                  key: PROJ
                  name: My Project
                status:
                  name: To Do
                priority:
                  name: High
    jira:issue_updated:
      name: jira:issue_updated
      title: Issue Updated
      summary: Fired when an existing issue is updated in Jira.
      description: >-
        Triggered when a user updates an issue. This includes field changes,
        status transitions, comments added, and other modifications. The
        payload includes the changelog showing what changed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/IssueWebhookPayload'
    jira:issue_deleted:
      name: jira:issue_deleted
      title: Issue Deleted
      summary: Fired when an issue is deleted from Jira.
      description: >-
        Triggered when a user deletes an issue. The payload includes the issue
        details as they were before deletion.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/IssueWebhookPayload'
    comment_created:
      name: comment_created
      title: Comment Created
      summary: Fired when a comment is added to an issue.
      description: >-
        Triggered when a user adds a comment to an issue. The payload includes
        the full comment details and the associated issue.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CommentWebhookPayload'
    comment_updated:
      name: comment_updated
      title: Comment Updated
      summary: Fired when an existing comment on an issue is edited.
      description: >-
        Triggered when a user edits a comment on an issue. The payload includes
        the updated comment details and the associated issue.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CommentWebhookPayload'
    comment_deleted:
      name: comment_deleted
      title: Comment Deleted
      summary: Fired when a comment is removed from an issue.
      description: >-
        Triggered when a user deletes a comment from an issue. The payload
        includes the deleted comment details and the associated issue.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CommentWebhookPayload'
    issuelink_created:
      name: issuelink_created
      title: Issue Link Created
      summary: Fired when a link between issues is created.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/IssueLinkWebhookPayload'
    issuelink_deleted:
      name: issuelink_deleted
      title: Issue Link Deleted
      summary: Fired when a link between issues is removed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/IssueLinkWebhookPayload'
    attachment_created:
      name: attachment_created
      title: Attachment Created
      summary: Fired when an attachment is added to an issue.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BaseWebhookPayload'
    attachment_deleted:
      name: attachment_deleted
      title: Attachment Deleted
      summary: Fired when an attachment is removed from an issue.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BaseWebhookPayload'
    worklog_created:
      name: worklog_created
      title: Worklog Created
      summary: Fired when a worklog entry is added to an issue.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/WorklogWebhookPayload'
    worklog_updated:
      name: worklog_updated
      title: Worklog Updated
      summary: Fired when a worklog entry is edited on an issue.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/WorklogWebhookPayload'
    worklog_deleted:
      name: worklog_deleted
      title: Worklog Deleted
      summary: Fired when a worklog entry is removed from an issue.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/WorklogWebhookPayload'
    project_created:
      name: project_created
      title: Project Created
      summary: Fired when a new project is created.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ProjectWebhookPayload'
    project_updated:
      name: project_updated
      title: Project Updated
      summary: Fired when a project is updated.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ProjectWebhookPayload'
    project_deleted:
      name: project_deleted
      title: Project Deleted
      summary: Fired when a project is permanently deleted.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ProjectWebhookPayload'
    project_soft_deleted:
      name: project_soft_deleted
      title: Project Soft Deleted
      summary: Fired when a project is moved to the trash.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ProjectWebhookPayload'
    project_restored_deleted:
      name: project_restored_deleted
      title: Project Restored from Trash
      summary: Fired when a project is restored from the trash.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ProjectWebhookPayload'
    sprint_created:
      name: sprint_created
      title: Sprint Created
      summary: Fired when a sprint is created.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SprintWebhookPayload'
    sprint_updated:
      name: sprint_updated
      title: Sprint Updated
      summary: Fired when a sprint is updated.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SprintWebhookPayload'
    sprint_deleted:
      name: sprint_deleted
      title: Sprint Deleted
      summary: Fired when a sprint is deleted.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SprintWebhookPayload'
    sprint_started:
      name: sprint_started
      title: Sprint Started
      summary: Fired when a sprint is started.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SprintWebhookPayload'
    sprint_closed:
      name: sprint_closed
      title: Sprint Closed
      summary: Fired when a sprint is closed (completed).
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SprintWebhookPayload'
    board_created:
      name: board_created
      title: Board Created
      summary: Fired when a board is created.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BoardWebhookPayload'
    board_updated:
      name: board_updated
      title: Board Updated
      summary: Fired when a board is updated.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BoardWebhookPayload'
    board_deleted:
      name: board_deleted
      title: Board Deleted
      summary: Fired when a board is deleted.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BoardWebhookPayload'
    user_created:
      name: user_created
      title: User Created
      summary: Fired when a new user is created.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/UserWebhookPayload'
    user_updated:
      name: user_updated
      title: User Updated
      summary: Fired when a user account is updated.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/UserWebhookPayload'
    user_deleted:
      name: user_deleted
      title: User Deleted
      summary: Fired when a user account is deleted.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/UserWebhookPayload'
    option_voting_changed:
      name: option_voting_changed
      title: Voting Option Changed
      summary: Fired when the voting option is enabled or disabled.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BaseWebhookPayload'
    option_watching_changed:
      name: option_watching_changed
      title: Watching Option Changed
      summary: Fired when the watching option is enabled or disabled.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BaseWebhookPayload'
    option_unassigned_issues_changed:
      name: option_unassigned_issues_changed
      title: Unassigned Issues Option Changed
      summary: Fired when the unassigned issues option is changed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BaseWebhookPayload'
    option_subtasks_changed:
      name: option_subtasks_changed
      title: Sub-tasks Option Changed
      summary: Fired when the sub-tasks option is enabled or disabled.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BaseWebhookPayload'
    option_attachments_changed:
      name: option_attachments_changed
      title: Attachments Option Changed
      summary: Fired when the attachments option is enabled or disabled.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BaseWebhookPayload'
    option_issuelinks_changed:
      name: option_issuelinks_changed
      title: Issue Links Option Changed
      summary: Fired when the issue links option is enabled or disabled.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BaseWebhookPayload'
    option_timetracking_changed:
      name: option_timetracking_changed
      title: Time Tracking Option Changed
      summary: Fired when the time tracking option is enabled or disabled.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BaseWebhookPayload'
  schemas:
    BaseWebhookPayload:
      type: object
      description: Base fields present in all Jira webhook payloads.
      required:
        - timestamp
        - webhookEvent
      properties:
        timestamp:
          type: integer
          format: int64
          description: >-
            The Unix timestamp (in milliseconds) of when the event occurred.
        webhookEvent:
          type: string
          description: >-
            The event type identifier (e.g., jira:issue_created,
            jira:issue_updated, project_created).
        matchedWebhookIds:
          type: array
          description: The IDs of the webhooks that matched this event.
          items:
            type: integer
    IssueWebhookPayload:
      allOf:
        - $ref: '#/components/schemas/BaseWebhookPayload'
        - type: object
          properties:
            issue_event_type_name:
              type: string
              description: >-
                The specific issue event type (e.g., issue_created,
                issue_updated, issue_generic, issue_assigned,
                issue_comment_edited).
            user:
              $ref: '#/components/schemas/WebhookUser'
            issue:
              $ref: '#/components/schemas/WebhookIssue'
            changelog:
              $ref: '#/components/schemas/WebhookChangelog'
    CommentWebhookPayload:
      allOf:
        - $ref: '#/components/schemas/BaseWebhookPayload'
        - type: object
          properties:
            user:
              $ref: '#/components/schemas/WebhookUser'
            issue:
              $ref: '#/components/schemas/WebhookIssue'
            comment:
              $ref: '#/components/schemas/WebhookComment'
    IssueLinkWebhookPayload:
      allOf:
        - $ref: '#/components/schemas/BaseWebhookPayload'
        - type: object
          properties:
            issueLink:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                sourceIssueId:
                  type: integer
                  format: int64
                destinationIssueId:
                  type: integer
                  format: int64
                issueLinkType:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    name:
                      type: string
                    outwardName:
                      type: string
                    inwardName:
                      type: string
    WorklogWebhookPayload:
      allOf:
        - $ref: '#/components/schemas/BaseWebhookPayload'
        - type: object
          properties:
            worklog:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                self:
                  type: string
                  format: uri
                author:
                  $ref: '#/components/schemas/WebhookUser'
                updateAuthor:
                  $ref: '#/components/schemas/WebhookUser'
                timeSpent:
                  type: string
                timeSpentSeconds:
                  type: integer
                  format: int64
                created:
                  type: string
                  format: date-time
                updated:
                  type: string
                  format: date-time
                started:
                  type: string
                  format: date-time
                issueId:
                  type: integer
                  format: int64
    ProjectWebhookPayload:
      allOf:
        - $ref: '#/components/schemas/BaseWebhookPayload'
        - type: object
          properties:
            project:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                key:
                  type: string
                name:
                  type: string
                description:
                  type: string
                projectTypeKey:
                  type: string
                self:
                  type: string
                  format: uri
                projectLead:
                  $ref: '#/components/schemas/WebhookUser'
    SprintWebhookPayload:
      allOf:
        - $ref: '#/components/schemas/BaseWebhookPayload'
        - type: object
          properties:
            sprint:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                self:
                  type: string
                  format: uri
                state:
                  type: string
                  enum:
                    - future
                    - active
                    - closed
                name:
                  type: string
                startDate:
                  type: string
                  format: date-time
                endDate:
                  type: string
                  format: date-time
                completeDate:
                  type: string
                  format: date-time
                originBoardId:
                  type: integer
                  format: int64
                goal:
                  type: string
    BoardWebhookPayload:
      allOf:
        - $ref: '#/components/schemas/BaseWebhookPayload'
        - type: object
          properties:
            board:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                self:
                  type: string
                  format: uri
                name:
                  type: string
                type:
                  type: string
                  enum:
                    - scrum
                    - kanban
                    - simple
    UserWebhookPayload:
      allOf:
        - $ref: '#/components/schemas/BaseWebhookPayload'
        - type: object
          properties:
            user:
              $ref: '#/components/schemas/WebhookUser'
    WebhookUser:
      type: object
      description: A user as represented in webhook payloads.
      properties:
        self:
          type: string
          format: uri
        accountId:
          type: string
          description: The account ID of the user.
        accountType:
          type: string
          enum:
            - atlassian
            - app
            - customer
        displayName:
          type: string
        active:
          type: boolean
        timeZone:
          type: string
        avatarUrls:
          type: object
          properties:
            16x16:
              type: string
              format: uri
            24x24:
              type: string
              format: uri
            32x32:
              type: string
              format: uri
            48x48:
              type: string
              format: uri
    WebhookIssue:
      type: object
      description: An issue as represented in webhook payloads.
      properties:
        id:
          type: string
        key:
          type: string
        self:
          type: string
          format: uri
        fields:
          type: object
          properties:
            summary:
              type: string
            description:
              type: object
              description: Atlassian Document Format (ADF) representation.
            issuetype:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                subtask:
                  type: boolean
                iconUrl:
                  type: string
                  format: uri
            project:
              type: object
              properties:
                id:
                  type: string
                key:
                  type: string
                name:
                  type: string
                projectTypeKey:
                  type: string
            status:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                statusCategory:
                  type: object
                  properties:
                    id:
                      type: integer
                    key:
                      type: string
                    name:
                      type: string
            priority:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                iconUrl:
                  type: string
                  format: uri
            assignee:
              $ref: '#/components/schemas/WebhookUser'
            reporter:
              $ref: '#/components/schemas/WebhookUser'
            creator:
              $ref: '#/components/schemas/WebhookUser'
            labels:
              type: array
              items:
                type: string
            created:
              type: string
              format: date-time
            updated:
              type: string
              format: date-time
            resolution:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
          additionalProperties: true
    WebhookComment:
      type: object
      description: A comment as represented in webhook payloads.
      properties:
        self:
          type: string
          format: uri
        id:
          type: string
        author:
          $ref: '#/components/schemas/WebhookUser'
        body:
          type: object
          description: The comment body in ADF.
        updateAuthor:
          $ref: '#/components/schemas/WebhookUser'
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    WebhookChangelog:
      type: object
      description: A changelog included with issue update webhook events.
      properties:
        id:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: The human-readable name of the field changed.
              fieldtype:
                type: string
                description: The type of the field (e.g., jira, custom).
              fieldId:
                type: string
                description: The ID of the field changed.
              from:
                type:
                  - string
                  - 'null'
                description: The previous value ID.
              fromString:
                type:
                  - string
                  - 'null'
                description: The previous value as a string.
              to:
                type:
                  - string
                  - 'null'
                description: The new value ID.
              toString:
                type:
                  - string
                  - 'null'
                description: The new value as a string.