- URL:
- https://<root>/services/webhooks/settings
- Methods:
POST- Version Introduced:
- 11.2
Access requirements
Required privileges
The Sever Administrator API requires privilege-based access. An administrator must be assigned a specific user privilege, or role, to access any given endpoint. Listed below are the user privileges or roles an administrator can be assigned that provides access to this endpoint. If multiple privileges are listed, only one needs to be assigned to gain access.
Note that administrators assigned a custom role must also have the administrative View all content privilege assigned to them to access the API directory as an administrator. Additonally, any custom roles that include a webhook-related privilege must also include the general Publish server-based layers content privilege.
Tokens
This API requires token-based authentication. A token is automatically generated for administrators who sign in to the Server Administrator API directory's HTML interface. Tokens generated in this way are stored for the entirety of the session.
Those accessing the API directory outside of the HTML interface will need to acquire a session token from the generate operation in the Portal Directory API. For security reasons, all POST requests made to the Server Administrator API must include a token in the request body.
Description
The settings operation allows organization administrators to set the number of re-delivery attempts the system will make to deliver a payload to a receiver before the delivery is marked as a failure, as well as set the deactivation policy for service webhooks. The deactivation policy specifies the number of failures (number) that can occur over a specific number of days (days) before a service webhook is deactivated.
For example, if the policy is set to allow 5 failed attempts over 5 days, if there is 1 failed attempt every day for 5 days, the webhook will deactivate on the fifth day. If 3 failures occur one day, and then 2 failures occur the second day, the webhook would deactivate the second day. If 2 failures occur one day, no failures occur the second day, 2 failures occur the third day, but no failures occur the fourth or fifth day, the webhook will not deactivate. If failures occur the sixth day, that day is treated as the start of the next 5 day period, and if 3 more failed attempts occur within this new window of time the webhook will deactivate.
Request parameters
| Parameter | Details |
|---|---|
| This value specifies the number of attempts that will be made to deliver the webhook payloads. By default, the payload will attempt to be delivered 3 times. The value for the attempts must be an integer between 1 and 5. Example |
| This value specifies the length of time, in seconds, the system will wait to receive a response from the receiver. By default, the system will wait 10 seconds. The value for the number of seconds the system will wait must be an integer between 1 and 60 seconds. Example |
| This value specifies the amount of time, in seconds, between each payload delivery attempt. By default, the system will attempt to deliver another payload after 5 seconds if the previous attempt fails, until the number of attempts specified by the Example |
| This value specifies the number of failures that can happen over a specific number of days (specified by the Example |
| This value specifies the number of days a specific number of failures (specified by the Example |
| The response format. The default format is Values: |
Example usage
The following is a sample POST request for the settings operation:
POST /<context>/admin/services/webhooks/settings HTTP/1.1
Host: organization.example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
notificationAttempts=4¬ificationTimeOutInSeconds=30¬ificationElapsedTimeInSeconds=30&numberOfFailures=5&daysInPast=5&f=pjsonJSON Response example
{
"notificationAttempts": 4,
"notificationTimeOutInSeconds": 30,
"notificationElapsedTimeInSeconds": 30,
"daysInPast": 5,
"numberOfFailures": 5,
"status": "success"
}