Webhooks
Webhooks allow client apps to be notified by HTTP post requests when data changes in PageSeeder. A webhook can be configured to only send requests for certain event types, projects, groups or for server events, so it can be tailored to specific client apps.
Events
The following event types are supported by webhooks:
Admin
- webhook.ping
Group or project events
- comment.created
- comment.modified
- comment.archived
- comment.unarchived
- comment.deleted
- group.deleted, group.archived, group.modified
- groupproperties.modified
- groupfolder.created, groupfolder.deleted groupfolder.modified
- membership.created
- membership.modified
- membership.deleted
- publication.created
- publication.modified
- publication.deleted
- task.updated (changes to any
<task>
attributes or content). - workflow.updated (changes to any
<workflow>
attributes or content). - uri.created (includes upload).
- uri.modified (includes move, edit, etc. – any time
uri/@lastmodified
is changed). - uri.archived
- uri.deleted
Project events
- group.created
- project.deleted, project.archived, project.modified
Server events
- member.created
- member.modified
- member.deleted
- project.created
A uri/comment/task move between groups and a group/project rename produce a deleted
and possible created
(and modified
for uri) event with the relevant groups for each.
A task/workflow/external URI change produces a separate event for each group as the content for each group can be different.
Requests
- Webhook POST requests can be in XML or JSON format (shown following).
- Each request contains one or more webevents.
- Each webevent contains zero or more event groups (these are the PageSeeder groups the event affects).
- Each webevent also contains an object in either minimal (private and public IDs only) or basic format depending on the webhook configuration.
- For delete events, the object always has minimal format.
See Element reference for details on the following XML elements.
XML format
<webevents> <webhook id="123" [name="xyz"] /> <webevent id="[object id].[nano time]" datetime="2012-11-23T22:35:12+10:00" type="[object].[action]"> <event> <group id="" name=""> [<group .../> ...] </event> <webhook|uri|comment|task|workflow|membership|member|... id="" [name="[group name]"] [docid=""] [path=""] [username=""] [email=""] [...]> [...] </...> </webevent> ... </webevents>
The publication.*
events are generated for any URIs added to the publication or already in the publication which are modified, removed or deleted. They are represented in the web event XML as follows:
<webevents> <webhook id="123" [name="xyz"] /> <webevent id="[object id].[nano time]" datetime="2012-11-23T22:35:12+10:00" type="publication.modified"> <event> <group id="" name=""> </event> <publication id="mypub1" ... > [<added> <uri ... >...</uri> ... </added>] [<modified> <uri ... >...</uri> ... </modified>] [<removed> <uri ... >...</uri> ... </removed>] [<deleted> <uri id="123" /> </deleted>] </publication> </webevent> ... </webevents>
The same URI might appear to be added more than once to the same publication depending on the state of the internal publication cache.
JSON format
{ "webhook": { "id" : "123", "name" : "xyz" }, "webevents": [ { "id": "[object id].[nano time]", "datetime": "2012-11-23T22:35:12+10:00", "type": "[object].[action]", "event": [ {"id":"", "name":""} ], "webhook|uri|comment|task|...": { ... } }, ... ] }
Configuration
Webhooks can only be configured by PageSeeder administrators using the Web service API or the user interface by selecting the Admin > Client admin page and following the steps below.
Step 1: Create a client
On the Client admin page click the Clients button and then on Register new client. Enter the details required and click Register.
Most of the details are related to OAuth configuration so that the client app can also connect to PageSeeder and access data.
If a Webhook secret is entered, it is used to sign all POST requests to this client with an HMAC of the request body and send it in an X-PS-Signature
HTTP header. This is so the app can verify the POST is coming from PageSeeder. Following is an example Java code snippet that could be used to verify the signature:
import org.pageseeder.bridge.util.Base64; ... SecretKeySpec key = new SecretKeySpec( webhook_secret.getBytes(StandardCharsets.UTF_8), "AES"); Mac mac = Mac.getInstance("HmacSHA1"); mac.init(key); String signature = new String(Base64.encode(mac.doFinal(body)));
Step 2: Start the client application
When a webhook is created, it immediately sends a webhook.ping
event POST to the URL for the webhook. If the client app replies with HTTP 200 and HTTP header X-PS-Secret
set to the same value as was sent in that header on the POST, then the webhook status changes from “pending” to “active”.
This confirms that the client wishes to receive webhook POST requests from PageSeeder and helps guard against PageSeeder sending unwanted or SPAM requests. It is similar to the immediate confirmation mechanism described here http://resthooks.org/docs/security/ .
Therefore, it is a good idea to ensure the client app is running before creating a webhook. If it is not, a webhook.ping
event can be initiated at another time from the Client admin > Webhooks page once the app is accessible (this updates the status as above).
Step 3: Create a webhook
On the Client admin page, click the Webhooks button and then click Register new webhook. Choose the client, enter a URL plus other details (see following) if required and click Register.
- Object type: minimal – means that only private and public IDs are returned for the object (no other content). This includes no attributes for groupproperties,
id
only for comment, task, workflow, membership and the following: -
uri:
id, docid, path
-
member:
id, username, email
-
groupfolder:
id, path
-
group:
id, name
-
project:
id, name
-
webhook:
id, name
- Support insecure SSL – means that the SSL certificate is not checked when sending requests. This can be useful for development servers but must not be used for production.
- Event filters – means the events that are sent to this webhook. Multiple event types can be specified by selecting different event types repeatedly.
- Include server events – means include the following events which are not specific to a project or group:
member.created, member.modified, member.deleted, project.created
.
Check the Webhooks page to ensure the webhook has a status of “active”. Event POST requests are only sent to “active” webhooks.
Troubleshooting
Following are the possible status values for a webhook and the remedies required:
Status | Description | Remedy |
---|---|---|
pending | Awaiting confirmation of ping request | Start client app (as above) and click Ping on Webhooks page |
active | Ready to receive event POST requests | n/a |
disabled | Manually stopped from receiving events | Change status to “active” by clicking Ping on Webhooks page |
warning | Has failed POST requests that are still being retried | Fix problem with webhook URL and click Ping on Webhooks page to test |
unreachable | Has reached the maximum number of retries for failed POST requests (some events might be lost) | Fix problem with webhook URL and click Ping on Webhooks page to test. Optionally clear or update the client app cache for the missing events. |
error | Other fatal error (some events might be lost) | Click Ping on Webhooks page to test. Optionally clear or update the client app cache for the missing events. |
If any webhooks have status warning, unreachable or error, they are displayed on the Admin > Console page. View the Recent logs to see detailed messages.
Client app cache means any cache an app outside PageSeeder uses to cache PageSeeder data. This is different from the Webhook caches described following, which store jobs and events persistently so pending events can still be processed after PageSeeder is restarted.
Webhook caches
The following message might appear on the Console page:
The webhooks caches were corrupted probably due to an unclean shutdown so unprocessed events before the shutdown will not have been sent (see general logs).
In this case, view the General logs for the day the server was shutdown and look for the following lines in the general log to see if there were any unprocessed events. If any numbers are non-zero or these lines are missing, the client app caches might need to be cleared or updated for the missing events.
There was 0 unprocessed webhook events at shutdown. There was 0 unprocessed webhook jobs at shutdown. There was 0 unprocessed failed webhook jobs at shutdown.
The contents of the webhook caches can be viewed under the Cache section of the Admin > System info pages. Click info next to the webhook-events
, webhook-failed-jobs
or webhook-jobs
cache then click each entry to see detailed information.
Failed POST requests
Following are the rules used to process failed POST requests to a webhook URL:
- If POST fails with
3xx
or410
error, set webhook status tounreachable
and stop sending to that webhook. - If POST fails with
4xx
,5xx
or other error increment,RetryNumber
and retry again using exponential backoff after2retries x 10
seconds (e.g. 10s, 20s, 40s, 80s, ... ~12 hrs forwebhookRetries=12
). Also, set webhook status towarning
. - If
RetryNumber > webhookRetries
(see following), set webhook status tounreachable
and stop sending to that webhook
PageSeeder tries to send failed requests in the order they were created, but the client app must always check the event datetime stamp because events might be received out of order.
Global properties
If there are issues with memory, performance or failure processing, the following global properties can be adjusted to modify the system.
Property | Description | Default value |
---|---|---|
webhookRequestInterval | The number of seconds to collect webhook events into a batch before sending as a single request (0 means 0.5 seconds). | 5 |
webhookRequestSize | The maximum number of bytes in a single webhook request (requests are split if they exceed this limit). | 500000 |
webhookRetries | The maximum number of times a failed webhook request is resent before the webhook status is changed to “unreachable”. | 12 |