Confluence events

Forge apps can subscribe to Confluence events for:

Pages and blogs
Comments
Spaces
Attachments

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

Name	Type	Description
eventType	`string`	The event name such as `avi:confluence:created:page`.
atlassianId	`string`	The ID of the user that has caused the event.
content	`Content`	An object representing the page/blog.
prevContent	`Content`	Only for `avi:confluence:moved:page`. An object representing the old page.
originContentId	`string`	Only for `avi:confluence:copied:page`. The ID of the origin content that was copied.
oldSortedChildPageIds	`string[]`	Only for `avi:confluence:children_reordered:page`. The list of child page IDs before the reorder.
newSortedChildPageIds	`string[]`	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"
    }
  }
}

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

Name	Type	Description
eventType	`string`	The event name such as `avi:confluence:created:comment`.
atlassianId	`string`	The ID of the user that has caused the event.
content	`Content`	An 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

Name	Type	Description
eventType	`string`	The event name such as `avi:confluence:created:space:V2`.
atlassianId	`string`	The ID of the user that has caused the event.
space	`Space`	An 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

Name	Type	Description
eventType	`string`	The event name such as `avi:confluence:created:attachment`.
atlassianId	`string`	The ID of the user that has caused the event.
attachment	`Attachment`	An 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"
    }
  }
}