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 Blogs

Forge apps can subscribe to these Page, Live Doc, Blog, and task events:

  • Pages & 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
  • 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
  • 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, Live Doc, and Blog events require the OAuth scope read:confluence-content.summary.

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, 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/Live Doc/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";
  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 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, Live Doc, 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"
    }
  }
}

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, blogpost, 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.
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: