Webhooks in Confluence

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 when a page is created, or user account disabled. Using a webhook to do this means that your remote application doesn't have to periodically poll Confluence to determine whether an event has occurred.

See Managing Webhooks in the Confluence documentation for an overview of how webhooks work, and how they're secured.

Overview

To create a webhook you'll need to provide:

• A name for the webhook created (for example, "Webhook for my remote app").
• The URL where the callback should be sent.
• The specific events to post to the URL.

A simple webhook might look like this:

• Name: "My simple webhook"
• URL: https://www.example.endpoint.com/webhookreceiver
• Events: page_created, blog_created

Create a webhook

You can register a webhook using the REST API, or through the Confluence UI.

To create a webhook, POST the following, in JSON format to <CONFLUENCE_URL>/rest/api/webhooks

1
2
{
  "name": "Webhook title",
  "events": [
    "page_created",
    "page_removed",
    "page_updated"
  ],
 "configuration": {
    "secret": "a-secret-string"
  },
  "url": "http://example.endpoint.com",
  "active": true
}

Here's an example using cURL and basic authentication:

1
2
curl -u admin:password -X POST -H 'Content-Type: application/json' -d '{"name": "Page changes","events": ["page_created","page_removed","page_updated"],"url": "http://example.endpoint.com","active": true}' http://example.confluence.com/rest/api/webhooks/

The response returns the webhook in JSON with additional information, including the ID and created timestamp. The webhook is also now visible in the Confluence UI.

1
2
{
  "id":3,
  "name":"Page changes",
  "createdDate":1596420716699,
  "updatedDate":1596420716699,
  "events":[
    "page_removed",
    "page_created",
    "page_updated"],
  "configuration":{},
  "url":"http://example.endpoint.com",
  "active":true
}

Query existing webhook

To get a list of webhooks, or query the details of a particular webhook, execute GET to <confluence-url>/rest/api/webhooks/{webhook-id}

Here's an example using cURL and basic authentication:

1
2
curl -u admin:password -X GET -H "Content-Type: application/json" http://example.confluence:8090/rest/api/webhooks/

This will return details of every registered webhook. You can append a specific webhook ID to the end to get details of a specific webhook.

Delete a webhook

To unregister (that is, delete) a webhook via REST, execute DELETE to the following URL: <confluence-url>/rest/api/webhooks/{webhookId}

The example below would delete the webhook with ID 41:

1
2
curl -u admin:password -X DELETE -H "Content-Type: application/json" http://example.confluence:8090/rest/api/webhooks/41

No response is returned.

More methods

There are a number of other methods you can use, for example you can see the last invocation of a webhook, statistics of existing webhooks, or use a simple test method to check your endpoint is available.

See the REST API reference documentation for more information.