Managing Webhooks

Still need help?

The Atlassian Community is here for you.

Ask the community

Webhooks allow you to notify an application, or other external service, when certain events occur in Confluence. For example, you can configure webhooks to update an issue tracker, or trigger notifications in a chat tool.

On this page:

A webhook consists of:

  • One or more events – such as page creation, or space removed. You can select multiple events to trigger the webhook. 
  • A URL – the endpoint where you want Confluence to send the event payloads when a matching event happens.

Once created, Confluence will listen for these events, and send the event payload, in JSON format, to the URL you specified. 

Securing the webhook

Confluence uses webhook secrets to authenticate the payload. Combined with HTTPS, it helps ensure the message transmitted is the one that Confluence intended to send, and that the contents were not tampered with.

When you define a secret for a webhook, each request is signed via a Hash-based Message Authentication Code (HMAC). The default for this algorithm is HMACSha256. The header X-Hub-Signature is defined and contains the HMAC.

To authenticate the validity of the message payload, the receiver can perform the HMAC algorithm on the received body with the secret as the key to the HMAC algorithm. If the results don't match, it may indicate there was a problem with transmission that has caused the message payload to change. 

Create a new webhook

You need Confluence Administrator or System Administrator global permissions to create a webhook. 

To create a new webhook:

  1. Go to Administration  > General Configuration >Webhooks.
  2. Enter a title for your webhook.
  3. Enter the URL of the application or server.
  4. Enter a secret.  This is a string of up to 255 characters that you define. 
  5. Select Test connection to check you can reach the application or server.
  6. Choose the events that should trigger the webhook.
  7. Select Active to make your webhook available immediately. 
  8. Select Create

Screenshot: Creating a webhook to notify a chat application when a space is created or removed.


You can also create a webhook using the API. See Webhooks in the Confluence developer documentation. 

Triggering webhooks   

You can configure your webhook to be triggered by the following events.

EventTriggered when...
attachment_createda file is attached to a page or blog post
attachment_removed

a file is deleted (sent to the trash) from the attachments page

(not triggered when a version is deleted from the file history)

attachment_restoreda file is restored from the trash
attachment_trasheda file is purged from the trash
attachment_updateda new file version of is uploaded directly or by editing the file
blog_createda blog post is published
blog_removeda blog post is deleted (sent to the trash)
blog_restoreda blog post is restored from the trash
blog_trasheda blog post is purged from the trash
blog_updateda blog post is edited
blueprint_page_createda page is created from a blueprint (such as meeting notes, decision, or how-to)
comment_createda page comment, inline comment or file comment is made
comment_removeda page comment, inline comment, or file comment is deleted
comment_updateda page comment, inline comment, or file comment is edited
content_createda page, blog post, attachment (file), comment (page, inline, or file), or other file (such as a space logo) is created or uploaded.
content_restoreda page, blog post, or attachment (file) is restored from the trash 
content_trasheda page, blog post, or attachment (file) is purged from the trash
content_updateda page, blog post, attachment (file), or comment (page, inline, and file) is edited.

content_permissions_updated

a view or edit restriction is applied or removed from a page or blog post

group_created

a new group is created 
group_removeda group is deleted
label_addedan existing label is applied to a page, blog post, or space
label_created

a label is added for the first time (did not already exist)

label_deleteda label is removed from the last page, blog post, or space, and so ceases to exist
label_removeda label is removed from a page, blog post, or space

page_children_reordered

the default ordering of pages is changed to alphabetical in the Space Tools > Reorder pages tab

(is not triggered when you drag a page, or move a page, to change the page order)

page_created

a page is published for the first time, including pages created from a template or blueprint

page_moveda page is moved to a different position in the page tree, to a different parent page, or to another space
page_removeda page is deleted (sent to the trash)
page_restoreda page is restored from the trash
page_trasheda page is purged from the trash
page_updateda page is edited (triggered at the point the unpublished changes are published)
space_createda new space is created
space_logo_updateda new file is uploaded for use as the logo of a space
space_permissions_updated

space permissions are changed in the Space Tools > Permissions tab

(is not triggered when you edit space permissions using Inspect Permissions)

space_removeda space is deleted

space_updated

the space details (title, description, status) is updated in the Space Tools > Overview tab

theme_enabled

a specific theme or default theme is applied to to a space or the whole site 

user_created

a new user account is created
user_deactivateda user account is disabled
user_followedsomeone follows a user
user_reactivateda disabled user account is enabled
user_removeda user account is deleted 

Event payloads

Here's an example of the event payload for the page_trashed  event.  This is the raw data that's sent, in JSON format, to your endpoint. 

{ 
  "timestamp":1596182511300, 
  "event":"page_trashed", 
  "userKey":"ff80818154ec9913015501e194f601d8", 
  "page":{ 
     "id":309264476 
  } 
}

You'll note that the content is comprised mostly of IDs. This is to ensure that identifiable information is not stored by third party services, or leaked to users who do not have permission to see it.

Once received, you can use the REST API to interpret these IDs. See Confluence Server Rest API

Circuit breaking

To help protect your Confluence site, any webhooks that fail consistently, are skipped for a period of time. By default, if a webhook fails five times, it is considered unhealthy and is skipped, initially for 10 seconds. If it continues to fail, it will be gradually shipped for longer periods, up to 10 hours. 

A webhook may also be skipped if there are too many webhooks in flight. If there are 500 webhooks being invoked, further requests will be skipped until the number in flight drops below 500.

Last modified on Mar 22, 2022

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.