<webhook>
Summary
This element describes the configuration options for a webhook endpoint.
Usage context
| Permitted content | <client> |
|---|---|
| Permitted parent | <webhooks> |
Attributes
| Name | Type | Required | Description |
|---|---|---|---|
| created | xs:datetime | yes | The date and time the webhook was created |
| events | xs:string | no | A comma-separated list of webhook events |
| format | enum | yes | Whether it is posted as JSON (json) or XML (xml) |
| groups | xs:string | no | A comma-separated list of groups or empty for all groups |
| id | xs:long | yes | A unique ID for the webhook assigned by the system |
| insecuressl | boolean | yes | True to post data even on insecure SSL connection |
| modified | xs:datetime | yes | The date and time the webhook was last modified manually (does not include status updates) |
| name | xs:string | no | The name of this webhook |
| object | enum | yes | Whether the returned object is minimal or basic |
| projects | xs:string | no | A comma-separated list of projects or empty for all groups |
| server | boolean | yes | Whether the end point receive server events |
| status | enum | yes | The status of the webhook based on the last time it was used, might be modified manually |
| url | url | yes | The URL of the webhook endpoint on the client |
@events
The list of webhook events that the client should receive. PageSeeder uses this list to determine which events should be created. Whether the event is posted to a particular webhook also depends on the values of the @projects, @groups and @server attributes.
If this attribute is empty, then all events are posted to the webhook endpoint.
Specifying which events your app requires is better practice. It indicates which notifications your app relies upon, it improves PageSeeder’s performance, and it reduces the traffic between PageSeeder and your app.
Events use the format [object].[action]. To receive all events for a particular type of object, use * for the action. Invalid events are ignored.
PageSeeder always posts the webhook.ping event, so there is no need to include it.
Here are a few examples:
| @events | Meaning |
|---|---|
comment.created | Post only when a new comment is created on groups based on values of @groups and @projects attributes. |
comment.* | Post any event about a comment (archived, created, deleted, modified and unarchived) on groups based on values of @groups and @projects attributes. |
member.* | Post any member creation, deletion or modification (requires the server flag to be set to true) |
groupfolder.*,uri.* | Post any event about group folders and URIs on groups based on values of @groups and @projects attributes |
@format
Whether PageSeeder should post the data as JSON or XML to the endpoint.
@groups
A comma-separated list of the groups for which PageSeeder posts events. An empty list means any group.
If a @projects attribute also specifies some projects, it includes all the groups under these projects, so it is unnecessary to include groups from these projects in that case.
@insecuressl
When set to true, PageSeeder posts data to the endpoint even without checking whether the SSL certificate is valid.
This option is designed to let developers test their webhook on a local client application where the certificate is self-signed. It should always be set to false otherwise.
@object
The object type determines the amount of details returned by the <webevent> element.
| Object type | Description |
|---|---|
minimal | Include private and public identifiers only (for example @id and @name attributes) |
basic | Include optional data |
Whether you choose one or the other depends on the requirements of your system.
Use minimal when being able to identify updated or deleted objects is sufficient and the objects are retrieved when needed with additional requests. For example, to maintain a cache. The business logic using minimal is often simpler to maintain and it is more efficient for PageSeeder.
Use basic when you need additional details when you are notified of the update. While this might save you from making additional requests, this might put more strain on the server and usually involves a more complicated business logic on the client side.
Delete events always return the minimal object.
@projects
A comma-separated list of the projects for which PageSeeder posts webhook events. An empty list means any project. When a project is listed, any group or subproject under that project is automatically selected.
@server
Indicates whether server events are posted. Server events include project creation, server starts and member account events (creation, modification and deletion).
Member events cover only account creation, deletion and modification. To know when members join or leave a group, use membership events which are at group/project level.
@status
It is one of the following values based on the last time it was used. If it is not active, check the troubleshooting section of the webhooks guide.
Administrators can manually change the status after fixing issues affecting the Webhook URL, but it is updated automatically every time the data is posted to the Webhook URL.
| Status | Description |
|---|---|
| active | Ready to receive event POST requests |
| disabled | Manually stopped from receiving events |
| error | Other fatal error |
| pending | Awaiting confirmation of ping request |
| unreachable | Has reached the maximum number of retries for failed POST requests defined in webhookRetries global property |
| warning | Has failed POST requests that are still being retried |
If the status is error or unreachable, some events might have been lost.
@url
The URL of the webhook endpoint on the client application.
For example, if the webhook URL is https://app.example.org/webhook, PageSeeder sends the events to that URL using the POST method.
During local development, set the insecuressl to true if you use self-signed certificates.
The webhook endpoint must be able to return the X-PS-Secret header in its response in order to successfully ping.
If the client associated with the webhook specifies a secret, the endpoint must also verify the signature specified in the X-PS-Signature request header.
Examples
The general format for a single webhook in XML is as follows:
<webhook id=""
created=""
modified=""
url=""
server="[true|false]"
[name=""]
[projects=""]
[groups=""]
[events=""]
object="[minimal|basic]"
format="[xml|json]"
insecuressl="[true|false]"
status="[pending|active|disabled|warning|error|unreachable]">
<client ...>
<member ...> ... </member>
</client>
</webhook>Example 1
The following example represents an active webhook which posts all comment events in groups under the demo project, to the https://app.example.org/webhook URL using the minimal JSON format.
<webhook id="123"
created="2022-10-12T14:16:23+11:00"
modified="2022-10-12T15:18:42+11:00"
url="https://app.example.org/webhook"
server="false"
name="Webhook Demo"
events="comments.*"
object="minimal"
project="demo"
format="json"
insecuressl="false"
status="active">
<!-- client -->
</webhook>Example 2
The following example represents a newly created webhook which posts all member events and the server started event to https://app.localhost/webhook URL using the minimal XML format.
<webhook id="456"
created="2022-10-12T14:17:33+11:00"
modified="2022-10-12T14:18:21+11:00"
url="https://app.localhost/webhook"
server="true"
name="Webhook Local Test"
events="server.started,member.*"
object="minimal"
format="xml"
insecuressl="true"
status="pending">
<!-- client -->
</webhook>Schema
XML Schema
<xs:element name="webhook">
<xs:element ref="client" />
<xs:attribute name="created" type="xs:dateTime" required="true"/>
<xs:attribute name="events" type="xs:string" />
<xs:attribute name="format" type="webhook-format" required="true"/>
<xs:attribute name="groups" type="xs:string" required="true"/>
<xs:attribute name="id" type="xs:long" required="true"/>
<xs:attribute name="insecuressl" type="xs:boolean" required="true"/>
<xs:attribute name="modified" type="xs:dateTime" required="true" />
<xs:attribute name="name" type="webhook-name" />
<xs:attribute name="object" type="webhook-object" required="true"/>
<xs:attribute name="projects" type="xs:string" />
<xs:attribute name="server" type="xs:boolean" required="true" />
<xs:attribute name="status" type="webhook-status" required="true"/>
<xs:attribute name="url" type="xs:anyURI" required="true" />
</xs:element>
<xs:simpleType name="webhook-name">
<xs:restriction base="xs:string">
<xs:maxLength value="100"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="webhook-object">
<xs:restriction base="xs:string">
<xs:enumeration value="minimal" />
<xs:enumeration value="basic" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="webhook-format">
<xs:restriction base="xs:string">
<xs:enumeration value="xml" />
<xs:enumeration value="json" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="webhook-status">
<xs:restriction base="xs:string">
<xs:enumeration value="pending" />
<xs:enumeration value="active" />
<xs:enumeration value="disabled" />
<xs:enumeration value="warning" />
<xs:enumeration value="error" />
<xs:enumeration value="unreachable" />
</xs:restriction>
</xs:simpleType>Compatibility
Webhooks were introduced in version 5.9500.