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 and blogs

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

  • Pages
    • Created: avi:confluence:created:page
    • Updated: avi:confluence:updated:page
    • 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
  • Blogs
    • Created: avi:confluence:created:blogpost
    • Updated: avi:confluence:updated:blogpost
    • Liked: avi:confluence:liked:blogpost
    • Viewed: avi:confluence:viewed:blogpost
  • Tasks
    • Created: avi:confluence:created:task
    • Updated: avi:confluence:updated:task
    • Removed: avi:confluence:removed:task

Page and blog events require the OAuth scope read:confluence-content.summary.

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

Page, blog, 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.
contentContentAn object representing the page/blog.
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";
  status: "current" | "trashed" | "historical" | "draft" | "archived";
  title: string;
  space: Space;
  history: History;
}

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

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

/**
 * Represents a user
 */
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",
      "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
      },
      "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
  • Databases
    • Created: avi:confluence:created:database
    • Moved: avi:confluence:updated:database
    • Copied: avi:confluence:copied: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

These events share the same payload format as pages, blogs, 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

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.
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;
  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;
  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 or blog 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/blog.

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

Space events require the same OAuth scope - read:confluence-space.summary, and 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.
spaceSpaceAn object representing the space.

Type reference

1
2
interface Space {
  id: number;
  key: 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",
    "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

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.
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;
  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;
  createdDate: string;
}

/**
 * The page or blog 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 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",
      "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
      },
      "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
        },
        "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"
    }
  }
}

Rate this page: