Managing Webhooks
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:
- Go to Administration
> General Configuration >Webhooks. - Enter a title for your webhook.
- Enter the URL of the application or server.
- Enter a secret. This is a string of up to 255 characters that you define.
- Select Test connection to check you can reach the application or server.
- Choose the events that should trigger the webhook.
- Select Active to make your webhook available immediately.
- 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.
| Event | Triggered when... |
|---|---|
| attachment_created | a 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_restored | a file is restored from the trash |
| attachment_trashed | a file is purged from the trash |
| attachment_updated | a new file version of is uploaded directly or by editing the file |
| blog_created | a blog post is published |
| blog_removed | a blog post is deleted (sent to the trash) |
| blog_restored | a blog post is restored from the trash |
| blog_trashed | a blog post is purged from the trash |
| blog_updated | a blog post is edited |
| blueprint_page_created | a page is created from a blueprint (such as meeting notes, decision, or how-to) |
| comment_created | a page comment, inline comment or file comment is made |
| comment_removed | a page comment, inline comment, or file comment is deleted |
| comment_updated | a page comment, inline comment, or file comment is edited |
| content_created | a page, blog post, attachment (file), comment (page, inline, or file), or other file (such as a space logo) is created or uploaded. |
| content_restored | a page, blog post, or attachment (file) is restored from the trash |
| content_trashed | a page, blog post, or attachment (file) is purged from the trash |
| content_updated | a 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_removed | a group is deleted |
| label_added | an 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_deleted | a label is removed from the last page, blog post, or space, and so ceases to exist |
| label_removed | a 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_moved | a page is moved to a different position in the page tree, to a different parent page, or to another space |
| page_removed | a page is deleted (sent to the trash) |
| page_restored | a page is restored from the trash |
| page_trashed | a page is purged from the trash |
| page_updated | a page is edited (triggered at the point the unpublished changes are published) |
| space_created | a new space is created |
| space_logo_updated | a 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_removed | a 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_deactivated | a user account is disabled |
| user_followed | someone follows a user |
| user_reactivated | a disabled user account is enabled |
| user_removed | a 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.