Product events

Confluence events

Forge apps can subscribe to Confluence events for:

Your Forge app must have permission from the site admin to access the data it provides within the event payload. The OAuth scope required for each event is documented below.

Pages, live docs, and blog posts

Forge apps can subscribe to these page, live doc, blog post, and task events:

  • Pages and live docs
    • Liked: avi:confluence:liked:page
    • Viewed: avi:confluence:viewed:page
    • Archived: avi:confluence:archived:page
    • Unarchived: avi:confluence:unarchived:page
    • Moved: avi:confluence:moved:page
    • Copied: avi:confluence:copied:page
    • Children reordered: avi:confluence:children_reordered:page
    • Permissions updated: avi:confluence:permissions_updated:page
    • Trashed: avi:confluence:trashed:page
    • Restored: avi:confluence:restored:page
  • Pages
    • Created: avi:confluence:created:page
    • Updated: avi:confluence:updated:page
  • Live docs
    • Created: avi:confluence:initialized:page
    • End of first edit session: avi:confluence:started:page
    • End of subsequent editing sessions: avi:confluence:snapshotted:page
    • Converted to page: avi:confluence:published:page
  • Blog posts
    • Created: avi:confluence:created:blogpost
    • Updated: avi:confluence:updated:blogpost
    • Liked: avi:confluence:liked:blogpost
    • Viewed: avi:confluence:viewed:blogpost
    • Permissions updated: avi:confluence:permissions_updated:blogpost
    • Trashed: avi:confluence:trashed:blogpost
    • Restored: avi:confluence:restored:blogpost
  • Tasks
    • Created: avi:confluence:created:task
    • Updated: avi:confluence:updated:task
    • Removed: avi:confluence:removed:task

Page, live doc, and blog post events require the OAuth scope read:confluence-content.summary.

Trashed events, in addition to the above, require the OAuth scope write:confluence-content. This requirement may be removed in the future.

Task events require the OAuth scope read:confluence-content.all.

Events such as avi:confluence:moved:page which apply to both pages and live docs will have a subType="live" field added in their payload if emitted by a live doc.

Page, live doc, blog post, and task events share the same payload format, with the exception of some events that have additional fields (see below).

Payload

NameTypeDescription
eventTypestringThe event name such as avi:confluence:created:page.
atlassianIdstringThe ID of the user that has caused the event. Absent if the event was triggered by an anonymous user.
contentContentAn object representing the page, live doc or blog post.
prevContentContentOnly for avi:confluence:moved:page. An object representing the old page.
originContentIdstringOnly for avi:confluence:copied:page. The ID of the origin content that was copied.
oldSortedChildPageIdsstring[]Only for avi:confluence:children_reordered:page. The list of child page IDs before the reorder.
newSortedChildPageIdsstring[]Only for avi:confluence:children_reordered:page. The list of child page IDs after the reorder.

Type reference

1
2
interface Content {
  id: string;
  type: "blogpost" | "page";
  subType?: "live"; // Included only if the page is a live doc.
  status: "current" | "trashed" | "historical" | "draft" | "archived";
  title: string;
  space: Space;
  history: History;
}

/**
 * The space the page, live doc, or blog post is located in.
 */
interface Space {
  id: number;
  key: string;
  alias: string;
  name: string;
  type: "global" | "personal";
  icon: Image;
  status: "current" | "archived";
}

/**
 * Information about the version of the page, live doc, or blog post that the event is related to
 * (always the latest version).
 */
interface History {
  latest: boolean;
  createdBy: User;
  ownedBy: User;
  createdDate: string;
}

/**
 * Represents a user.
 *
 * Note that personally identifiable information (username, email,
 * publicName, and displayName) is populated with the accountId instead
 * for privacy reasons.
 */
interface User {
  type: "known" | "unknown" | "anonymous" | "user";
  username: string;
  accountId: string;
  accountType: "atlassian" | "app";
  email: string;
  profilePicture: Image;
  displayName: string;
  isExternalCollaborator: boolean;
}

/**
 * Represents an image shown in the UI.
 */
interface Image {
  path: string;
  width: number;
  height: number;
  isDefault: boolean;
}

Example

This is an example of an event triggered when a page is created.

1
2
{
  "eventType": "avi:confluence:created:page",
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "content": {
    "id": "838205441",
    "type": "page",
    "status": "current",
    "title": "A brand new page",
    "space": {
      "id": 827392002,
      "key": "SP",
      "alias": "SP",
      "name": "Project: Sample Project",
      "icon": {
        "path": "/images/logo/default-space-logo-256.png",
        "width": 48,
        "height": 48,
        "isDefault": false
      },
      "type": "global",
      "status": "current"
    },
    "history": {
      "latest": true,
      "createdBy": {
        "type": "known",
        "username": "4ad9aa0c52dc1b420a791d12",
        "accountId": "4ad9aa0c52dc1b420a791d12",
        "accountType": "atlassian",
        "email": "4ad9aa0c52dc1b420a791d12",
        "publicName": "4ad9aa0c52dc1b420a791d12",
        "profilePicture": {
          "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
          "width": 48,
          "height": 48,
          "isDefault": false
        },
        "displayName": "4ad9aa0c52dc1b420a791d12",
        "isExternalCollaborator": false
      },
      "ownedBy": {
        "type": "known",
        "username": "4ad9aa0c52dc1b420a791d12",
        "accountId": "4ad9aa0c52dc1b420a791d12",
        "accountType": "atlassian",
        "email": "4ad9aa0c52dc1b420a791d12",
        "publicName": "4ad9aa0c52dc1b420a791d12",
        "profilePicture": {
          "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
          "width": 48,
          "height": 48,
          "isDefault": false
        },
        "displayName": "4ad9aa0c52dc1b420a791d12",
        "isExternalCollaborator": false
      },
      "createdDate": "2021-01-20T06:29:21.707Z"
    }
  }
}

Whiteboards, databases, smart links, and folders

Forge apps can subscribe to these whiteboard, database, smart link in the content tree, and folder events:

  • Whiteboards
    • Created: avi:confluence:created:whiteboard
    • Moved: avi:confluence:updated:whiteboard
    • Copied: avi:confluence:copied:whiteboard
    • Permissions updated: avi:confluence:permissions_updated:whiteboard
  • Databases
    • Created: avi:confluence:created:database
    • Moved: avi:confluence:updated:database
    • Copied: avi:confluence:copied:database
    • Permissions updated: avi:confluence:permissions_updated:database
  • Smart links in the content tree
    • Created: avi:confluence:created:embed
    • Moved: avi:confluence:updated:embed
    • Copied: avi:confluence:copied:embed
  • Folders
    • Created: avi:confluence:created:folder
    • Moved: avi:confluence:updated:folder
    • Copied: avi:confluence:copied:folder
    • Permissions updated: avi:confluence:permissions_updated:folder

These events share the same payload format as page, blog post, and task events. They also require the OAuth scope read:confluence-content.summary.

Comments

Forge apps can subscribe to the following comment events:

  • Created: avi:confluence:created:comment
  • Updated: avi:confluence:updated:comment
  • Liked: avi:confluence:liked:comment
  • Deleted: avi:confluence:deleted:comment

Comment events require the OAuth scope read:confluence-content.summary and share the same payload format.

Payload

NameTypeDescription
eventTypestringThe event name such as avi:confluence:created:comment.
atlassianIdstringThe ID of the user that has caused the event. Absent if the event was triggered by an anonymous user.
contentContentAn object representing the comment.

Type reference

1
2
interface Content {
  id: string;
  type: "comment";
  status: "current" | "trashed" | "historical" | "draft";
  title: string;
  space: Space;
  history: History;
  ancestors: Ancestors;
  container: CommentContainer;
  extensions: {
    location: "footer" | "inline";
  };
}

/**
 * The space the comment is located in.
 */
interface Space {
  id: number;
  key: string;
  alias: string;
  name: string;
  type: "global" | "personal";
  icon: Image;
  status: "current" | "archived";
}

/**
 * Information about the version of the comment that the event is related to
 * (always the latest version).
 */
interface History {
  latest: boolean;
  createdBy: User;
  ownedBy: User;
  createdDate: string;
}

/**
 * If this comment is part of a thread of replies, then this contains a list of all comments before
 * this particular comment, sorted from newest to oldest. Otherwise, it’s an empty array.
 */
type Ancestors = Content[];

/**
 * The page, blog post or custom content the comment is located in.
 * Container field is absent for ancestors since it’s the same as for the original comment.
 */
interface CommentContainer {
  id: number;
  type: string;
  status: "current" | "trashed" | "historical" | "draft" | "archived";
  title: string;
  history: History;
  space: Space;
}

/**
 * Represents a user.
 *
 * Note that personally identifiable information (username, email,
 * publicName, and displayName) is populated with the accountId instead
 * for privacy reasons.
 */
interface User {
  type: "known" | "unknown" | "anonymous" | "user";
  username: string;
  accountId: string;
  accountType: "atlassian" | "app";
  email: string;
  profilePicture: Image;
  displayName: string;
  isExternalCollaborator: boolean;
}

/**
 * Represents an image shown in the UI.
 */
interface Image {
  path: string;
  width: number;
  height: number;
  isDefault: boolean;
}

Example

This is an example of an event triggered when a new comment is posted on a page.

1
2
{
  "eventType": "avi:confluence:created:comment",
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "content": {
    "id": "838205455",
    "type": "comment",
    "status": "current",
    "title": "Re: A brand new page",
    "space": {
      "id": 827392002,
      "key": "SP",
      "alias": "SP",
      "name": "Project: Sample Project",
      "icon": {
        "path": "/images/logo/default-space-logo-256.png",
        "width": 48,
        "height": 48,
        "isDefault": false
      },
      "type": "global",
      "status": "current"
    },
    "history": {
      "latest": true,
      "createdBy": {
        "type": "known",
        "username": "4ad9aa0c52dc1b420a791d12",
        "accountId": "4ad9aa0c52dc1b420a791d12",
        "accountType": "atlassian",
        "email": "4ad9aa0c52dc1b420a791d12",
        "publicName": "4ad9aa0c52dc1b420a791d12",
        "profilePicture": {
          "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
          "width": 48,
          "height": 48,
          "isDefault": false
        },
        "displayName": "4ad9aa0c52dc1b420a791d12",
        "isExternalCollaborator": false
      },
      "ownedBy": {
        "type": "known",
        "username": "4ad9aa0c52dc1b420a791d12",
        "accountId": "4ad9aa0c52dc1b420a791d12",
        "accountType": "atlassian",
        "email": "4ad9aa0c52dc1b420a791d12",
        "publicName": "4ad9aa0c52dc1b420a791d12",
        "profilePicture": {
          "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
          "width": 48,
          "height": 48,
          "isDefault": false
        },
        "displayName": "4ad9aa0c52dc1b420a791d12",
        "isExternalCollaborator": false
      },
      "createdDate": "2021-01-20T07:10:41.070Z"
    },
    "ancestors": [],
    "container": {
      "id": "838205441",
      "type": "page",
      "status": "current",
      "title": "A brand new page",
      "history": {
        "latest": true,
        "createdBy": {
          "type": "known",
          "username": "4ad9aa0c52dc1b420a791d12",
          "accountId": "4ad9aa0c52dc1b420a791d12",
          "accountType": "atlassian",
          "email": "4ad9aa0c52dc1b420a791d12",
          "publicName": "4ad9aa0c52dc1b420a791d12",
          "profilePicture": {
            "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
            "width": 48,
            "height": 48,
            "isDefault": false
          },
          "displayName": "4ad9aa0c52dc1b420a791d12",
          "isExternalCollaborator": false
        },
        "ownedBy": {
          "type": "known",
          "username": "4ad9aa0c52dc1b420a791d12",
          "accountId": "4ad9aa0c52dc1b420a791d12",
          "accountType": "atlassian",
          "email": "4ad9aa0c52dc1b420a791d12",
          "publicName": "4ad9aa0c52dc1b420a791d12",
          "profilePicture": {
            "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
            "width": 48,
            "height": 48,
            "isDefault": false
          },
          "displayName": "4ad9aa0c52dc1b420a791d12",
          "isExternalCollaborator": false
        },
        "createdDate": "2021-01-20T06:29:21.707Z"
      }
    },
    "extensions": {
      "location": "footer"
    }
  }
}

Spaces

Forge apps can subscribe to the following space events:

  • Created: avi:confluence:created:space:V2
  • Updated: avi:confluence:updated:space:V2
  • Permissions updated: avi:confluence:permissions_updated:space:V2

Space events require the same OAuth scope - read:confluence-space.summary.

Event avi:confluence:permissions_updated:space:V2, in addition to the above, requires the OAuth scope write:confluence-space. This requirement may be removed in the future.

All space events share the same payload format.

Payload

NameTypeDescription
eventTypestringThe event name such as avi:confluence:created:space:V2.
atlassianIdstringThe ID of the user that has caused the event. Absent if the event was triggered by an anonymous user.
spaceSpaceAn object representing the space.

Type reference

1
2
interface Space {
  id: number;
  key: string;
  alias: string;
  name: string;
  type: "global" | "personal";
  icon: Image;
  status: "current" | "archived";
}

/**
 * Represents an image shown in the UI.
 */
interface Image {
  path: string;
  width: number;
  height: number;
  isDefault: boolean;
}

This is an example of an event triggered when a space is created.

1
2
{
  "eventType": "avi:confluence:created:space:V2",
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "space": {
    "id": 827392002,
    "key": "SP",
    "alias": "SP",
    "name": "Project: Sample Project",
    "icon": {
      "path": "/images/logo/default-space-logo-256.png",
      "width": 48,
      "height": 48,
      "isDefault": false
    },
    "type": "global",
    "status": "current"
  }
}

Attachments

Forge apps can subscribe to the following attachment events:

  • Created: avi:confluence:created:attachment
  • Updated: avi:confluence:updated:attachment
  • Viewed: avi:confluence:viewed:attachment
  • Archived: avi:confluence:archived:attachment
  • Unarchived: avi:confluence:unarchived:attachment
  • Trashed: avi:confluence:trashed:attachment
  • Restored: avi:confluence:restored:attachment

Attachment events require the OAuth scope read:confluence-content.summary and share the same payload format.

Payload

NameTypeDescription
eventTypestringThe event name such as avi:confluence:created:attachment.
atlassianIdstringThe ID of the user that has caused the event. Absent if the event was triggered by an anonymous user.
attachmentAttachmentAn object representing the attachment.

Type reference

1
2
interface Attachment {
  id: number;
  type: "attachment";
  status: "current" | "trashed" | "historical" | "draft" | "archived";
  title: string;
  space: Space;
  history: History;
  container: AttachmentContainer;
  extensions: Extensions;
}

/**
 * The space the attachment is located in.
 */
interface Space {
  id: number;
  key: string;
  alias: string;
  name: string;
  type: "global" | "personal";
  icon: Image;
  status: "current" | "archived";
}

/**
 * Information about the version of the attachment that the event is related to
 * (always the latest version).
 */
interface History {
  latest: boolean;
  createdBy: User;
  ownedBy: User;
  createdDate: string;
}

/**
 * The page, blog post or custom content the attachment is located in.
 */
interface AttachmentContainer {
  id: number;
  type: string;
  status: "current" | "trashed" | "historical" | "draft" | "archived";
  title: string;
  history: History;
  space: Space;
}

/**
 * Represents an additional piece of information about the attachment.
 */
interface Extensions {
  mediaType: string;
  fileSize: number;
  mediaTypeDescription: string;
  fileId: string;
  downloadPath: string;
}

/**
 * Represents a user.
 *
 * Note that personally identifiable information (username, email,
 * publicName, and displayName) is populated with the accountId instead
 * for privacy reasons.
 */
interface User {
  type: "known" | "unknown" | "anonymous" | "user";
  username: string;
  accountId: string;
  accountType: "atlassian" | "app";
  email: string;
  profilePicture: Image;
  displayName: string;
  isExternalCollaborator: boolean;
}

/**
 * Represents an image shown in the UI.
 */
interface Image {
  path: string;
  width: number;
  height: number;
  isDefault: boolean;
}

This is an example of an event triggered when an attachment is created.

1
2
{
  "eventType": "avi:confluence:created:attachment",
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "attachment": {
    "id": "838205455",
    "type": "attachment",
    "status": "current",
    "title": "logo.png",
    "space": {
      "id": 827392002,
      "key": "SP",
      "alias": "SP",
      "name": "Project: Sample Project",
      "icon": {
        "path": "/images/logo/default-space-logo-256.png",
        "width": 48,
        "height": 48,
        "isDefault": false
      },
      "type": "global",
      "status": "current"
    },
    "history": {
      "latest": true,
      "createdBy": {
        "type": "known",
        "username": "4ad9aa0c52dc1b420a791d12",
        "accountId": "4ad9aa0c52dc1b420a791d12",
        "accountType": "atlassian",
        "email": "4ad9aa0c52dc1b420a791d12",
        "publicName": "4ad9aa0c52dc1b420a791d12",
        "profilePicture": {
          "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
          "width": 48,
          "height": 48,
          "isDefault": false
        },
        "displayName": "4ad9aa0c52dc1b420a791d12",
        "isExternalCollaborator": false
      },
      "ownedBy": {
        "type": "known",
        "username": "4ad9aa0c52dc1b420a791d12",
        "accountId": "4ad9aa0c52dc1b420a791d12",
        "accountType": "atlassian",
        "email": "4ad9aa0c52dc1b420a791d12",
        "publicName": "4ad9aa0c52dc1b420a791d12",
        "profilePicture": {
          "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
          "width": 48,
          "height": 48,
          "isDefault": false
        },
        "displayName": "4ad9aa0c52dc1b420a791d12",
        "isExternalCollaborator": false
      },
      "createdDate": "2021-01-20T07:10:41.070Z"
    },
    "container": {
      "id": "838205441",
      "type": "page",
      "status": "current",
      "title": "A brand new page",
      "history": {
        "latest": true,
        "createdBy": {
          "type": "known",
          "username": "4ad9aa0c52dc1b420a791d12",
          "accountId": "4ad9aa0c52dc1b420a791d12",
          "accountType": "atlassian",
          "email": "4ad9aa0c52dc1b420a791d12",
          "publicName": "4ad9aa0c52dc1b420a791d12",
          "profilePicture": {
            "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
            "width": 48,
            "height": 48,
            "isDefault": false
          },
          "displayName": "4ad9aa0c52dc1b420a791d12",
          "isExternalCollaborator": false
        },
        "ownedBy": {
          "type": "known",
          "username": "4ad9aa0c52dc1b420a791d12",
          "accountId": "4ad9aa0c52dc1b420a791d12",
          "accountType": "atlassian",
          "email": "4ad9aa0c52dc1b420a791d12",
          "publicName": "4ad9aa0c52dc1b420a791d12",
          "profilePicture": {
            "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
            "width": 48,
            "height": 48,
            "isDefault": false
          },
          "displayName": "4ad9aa0c52dc1b420a791d12",
          "isExternalCollaborator": false
        },
        "createdDate": "2021-01-20T06:29:21.707Z"
      }
    },
    "extensions": {
      "mediaType": "image/png",
      "fileSize": "3329",
      "mediaTypeDescription": "PNG Image",
      "fileId": "b23c8f6f-5b24-401f-9f97-3e83650d858e",
      "collectionName": "contentId-753665",
      "downloadPath": "https://example.atlassian.net/wiki/download/attachments/838205441/logo.png?version=5&cacheVersion=1&api=v2"
    }
  }
}

Custom content

Forge apps can subscribe to the following custom content events:

  • Created: avi:confluence:created:custom_content
  • Updated: avi:confluence:updated:custom_content
  • Permissions updated: avi:confluence:permissions_updated:custom_content
  • Trashed: avi:confluence:trashed:custom_content
  • Restored: avi:confluence:restored:custom_content

Custom content events are triggered when an action is performed on a Connect or Forge custom content.

Custom content events require the OAuth scope read:confluence-content.summary and share the same payload format.

Payload

NameTypeDescription
eventTypestringThe event name such as avi:confluence:created:custom_content.
atlassianIdstringThe ID of the user that has caused the event. Absent if the event was triggered by an anonymous user.
contentContentAn object representing the custom content.

Type reference

1
2
interface Content {
  id: number;
  type: string; // Full Connect or Forge custom content type.
  status: "current" | "trashed" | "historical" | "draft" | "archived";
  title: string;
  space: Space;
  history: History;
  container?: CustomContentContainer; // Absent for space-level custom content.
}

/**
 * The space the custom content is located in.
 */
interface Space {
  id: number;
  key: string;
  alias: string;
  name: string;
  type: "global" | "personal";
  icon: Image;
  status: "current" | "archived";
}

/**
 * Information about the version of the custom content that the event is related to
 * (always the latest version).
 */
interface History {
  latest: boolean;
  createdBy: User;
  ownedBy: User;
  createdDate: string;
}

/**
 * The page, blog post or another custom content this custom content is located in.
 */
interface CustomContentContainer {
  id: number;
  type: string;
  status: "current" | "trashed" | "historical" | "draft" | "archived";
  title: string;
  space: Space;
}

/**
 * Represents a user.
 *
 * Note that personally identifiable information (username, email,
 * publicName, and displayName) is populated with the accountId instead
 * for privacy reasons.
 */
interface User {
  type: "known" | "unknown" | "anonymous" | "user";
  username: string;
  accountId: string;
  accountType: "atlassian" | "app";
  email: string;
  profilePicture: Image;
  displayName: string;
  isExternalCollaborator: boolean;
}

/**
 * Represents an image shown in the UI
 */
interface Image {
  path: string;
  width: number;
  height: number;
  isDefault: boolean;
}

Example

This is an example of an event triggered when a Forge custom content is created as a child of a page.

1
2
{
  "eventType": "avi:confluence:created:custom_content",
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "content": {
    "id": "838205552",
    "type": "forge:9149a1f2-9ed3-44ab-80e8-741adf4187fd:2edb9983-c665-4da2-a714-48572fb09cd0:my-custom-content",
    "status": "current",
    "title": "My custom content 001",
    "space": {
      "id": 827392002,
      "key": "SP",
      "alias": "SP",
      "name": "Project: Sample Project",
      "icon": {
        "path": "/images/logo/default-space-logo-256.png",
        "width": 48,
        "height": 48,
        "isDefault": false
      },
      "type": "global",
      "status": "current"
    },
    "history": {
      "latest": true,
      "createdBy": {
        "type": "known",
        "username": "4ad9aa0c52dc1b420a791d12",
        "accountId": "4ad9aa0c52dc1b420a791d12",
        "accountType": "atlassian",
        "email": "4ad9aa0c52dc1b420a791d12",
        "publicName": "4ad9aa0c52dc1b420a791d12",
        "profilePicture": {
          "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
          "width": 48,
          "height": 48,
          "isDefault": false
        },
        "displayName": "4ad9aa0c52dc1b420a791d12",
        "isExternalCollaborator": false
      },
      "ownedBy": {
        "type": "known",
        "username": "4ad9aa0c52dc1b420a791d12",
        "accountId": "4ad9aa0c52dc1b420a791d12",
        "accountType": "atlassian",
        "email": "4ad9aa0c52dc1b420a791d12",
        "publicName": "4ad9aa0c52dc1b420a791d12",
        "profilePicture": {
          "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
          "width": 48,
          "height": 48,
          "isDefault": false
        },
        "displayName": "4ad9aa0c52dc1b420a791d12",
        "isExternalCollaborator": false
      },
      "createdDate": "2021-01-20T07:10:41.070Z"
    },
    "container": {
      "id": "838205441",
      "type": "page",
      "status": "current",
      "title": "A brand new page"
    }
  }
}

Labels

Forge apps can subscribe to the following label events:

  • Created: avi:confluence:created:label
  • Added: avi:confluence:added:label
  • Removed: avi:confluence:removed:label
  • Deleted: avi:confluence:deleted:label

Label events are triggered when a label is created, added to an entity, removed from an entity, or deleted. A label can be associated with one of the following entities: content (such as a page, blog post, database, etc.), space, or page template. Only one of the fields (content, space, or template) will be present in the event payload, depending on the entity the label is associated with.

Label events require the following OAuth scopes:

  • read:confluence-content.summary
  • read:confluence-space.summary

Payload

NameTypeDescription
eventTypestringThe event name such as avi:confluence:added:label.
atlassianIdstringThe ID of the user that caused the event. Absent if the event was triggered by an anonymous user.
labelLabelThe label object.
contentContent(Optional) The content the label is associated with.
spaceSpace(Optional) The space the label is associated with.
templateTemplate(Optional) The template the label is associated with.

Type reference

1
2
interface Label {
  id: string;
  name: string;
  prefix: string; // "global", "team", "my", etc.
}

interface Content {
  id: string;
  type: "page" | "blogpost" | "attachment" | "whiteboard" | "database" | "embed" | "folder";
  subType?: "live"; // Included only if "type" value is "page" and this page is a live doc
  title: string;
  status: string;
  space: Space;
  history: History;
  labels: Label[]; // Existing labels on the content at the time of the event
}

interface Space {
  id: number;
  key: string;
  alias: string;
  name: string;
  type: "global" | "personal";
  icon: Image;
  status: "current" | "archived";
  labels: Label[]; // Existing labels on the space at the time of the event
}

interface Template {
  templateId: string;
  name: string;
  description: string;
  templateType: "page" | "blueprint";
  space?: Space; // Included only for space-level page templates (as opposed to global templates)
  labels: Label[]; // Existing labels on the template at the time of the event
}

interface History {
  latest: boolean;
  createdBy: User;
  ownedBy: User;
  createdDate: string;
}

interface User {
  type: "known" | "unknown" | "anonymous" | "user";
  username: string;
  accountId: string;
  accountType: "atlassian" | "app";
  email: string;
  profilePicture: Image;
  displayName: string;
  isExternalCollaborator: boolean;
}

interface Image {
  path: string;
  width: number;
  height: number;
  isDefault: boolean;
}

Examples

This is an example of an event triggered when a label is added to a live doc:

1
2
{
  "eventType": "avi:confluence:added:label",
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "label": {
    "id": "123456789",
    "name": "example-label",
    "prefix": "global"
  },
  "content": {
    "id": "838205441",
    "type": "page",
    "subType": "live",
    "title": "A brand new page",
    "status": "current",
    "space": {
      "id": 827392002,
      "key": "SP",
      "alias": "SP",
      "name": "Project: Sample Project",
      "icon": {
        "path": "/images/logo/default-space-logo-256.png",
        "width": 48,
        "height": 48,
        "isDefault": false
      },
      "type": "global",
      "status": "current"
    },
    "history": {
      "latest": true,
      "createdBy": {
        "type": "known",
        "username": "4ad9aa0c52dc1b420a791d12",
        "accountId": "4ad9aa0c52dc1b420a791d12",
        "accountType": "atlassian",
        "email": "4ad9aa0c52dc1b420a791d12",
        "publicName": "4ad9aa0c52dc1b420a791d12",
        "profilePicture": {
          "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
          "width": 48,
          "height": 48,
          "isDefault": false
        },
        "displayName": "4ad9aa0c52dc1b420a791d12",
        "isExternalCollaborator": false
      },
      "ownedBy": {
        "type": "known",
        "username": "4ad9aa0c52dc1b420a791d12",
        "accountId": "4ad9aa0c52dc1b420a791d12",
        "accountType": "atlassian",
        "email": "4ad9aa0c52dc1b420a791d12",
        "publicName": "4ad9aa0c52dc1b420a791d12",
        "profilePicture": {
          "path": "/wiki/aa-avatar/4ad9aa0c52dc1b420a791d12",
          "width": 48,
          "height": 48,
          "isDefault": false
        },
        "displayName": "4ad9aa0c52dc1b420a791d12",
        "isExternalCollaborator": false
      },
      "createdDate": "2021-01-20T06:29:21.707Z"
    },
    "labels": [
      {
        "id": "123456701",
        "name": "existing-label-1",
        "prefix": "global"
      },
      {
        "id": "123456702",
        "name": "existing-label-2",
        "prefix": "team"
      }
    ]
  }
}

This is an example of an event triggered when a label is added to a space:

1
2
{
  "eventType": "avi:confluence:added:label",
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "label": {
    "id": "123456789",
    "name": "example-label",
    "prefix": "global"
  },
  "space": {
    "id": 827392002,
    "key": "SP",
    "alias": "SP",
    "name": "Project: Sample Project",
    "icon": {
      "path": "/images/logo/default-space-logo-256.png",
      "width": 48,
      "height": 48,
      "isDefault": false
    },
    "type": "global",
    "status": "current",
    "labels": [
      {
        "id": "123456701",
        "name": "existing-label-1",
        "prefix": "global"
      },
      {
        "id": "123456702",
        "name": "existing-label-2",
        "prefix": "team"
      }
    ]
  }
}

This is an example of an event triggered when a label is added to a space-level page template:

1
2
{
  "eventType": "avi:confluence:added:label",
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "label": {
    "id": "123456789",
    "name": "example-label",
    "prefix": "global"
  },
  "template": {
    "templateId": "123456789",
    "name": "Example Template",
    "description": "A template for demonstration purposes.",
    "templateType": "page",
    "space": {
      "id": 827392002,
      "key": "SP",
      "alias": "SP",
      "name": "Project: Sample Project",
      "icon": {
        "path": "/images/logo/default-space-logo-256.png",
        "width": 48,
        "height": 48,
        "isDefault": false
      },
      "type": "global",
      "status": "current"
    },
    "labels": [
      {
        "id": "123456701",
        "name": "existing-label-1",
        "prefix": "global"
      },
      {
        "id": "123456702",
        "name": "existing-label-2",
        "prefix": "team"
      }
    ]
  }
}

Rate this page: