| On this page |
New
This feature was added in License Server 20.0.
As your organization grows so does your license needs. To get a deep understanding of how your licenses are being utilized and how the license server is performing webhooks can be used to paint that picture. The license server supports one webhook with several events you can subscribe too.
To setup your webhook open hkey.
-
click on File ▸ Webhooks… which will open the webhook dialog.
-
enter your webhook url at the top of the dialog. For example,
https://mycompany.sidefx.webhook:8080/. -
subscribe to any number of triggers that you are interested in receiving.
Url Verification ¶
When setting the url for the webhook the url must be verified that its actually valid and usable before any events can be sent to it. The webhook server must include the challenge from the request in its response otherwise the license server will mark the request as unsuccessful and disable the webhook. If for any reason the server was determined the url verification failed the webhook is disabled and no new events are sent. The server also does not queue these events while a new url is being verified.
request
{ "type": "url_verification", "challenge": "" }
Key |
Type |
Description |
|---|---|---|
type |
string |
The type of request thats being sent. This will always be |
challenge |
string |
The randomly generated challenge to ensure the response thats sent back from the webhook server was actually in response to the request from the license server. |
response
{ "challenge": "" }
Key |
Type |
Description |
|---|---|---|
challenge |
string |
The value of the challenge key in the request. This is required so that the license server can verify that the response is actually in response to the original request. |
Event Requests ¶
Each event is given three chances for a successful send. The first retry will be sent a minute after it was determined the request failed and the second retry will be sent 5 minutes after the first retry fails. A request is allowed to be redirected up to two times from a 3xx HTTP response from the webhook server. If the request is redirected more then twice then it will fail with failure reason too_many_redirects described below.
There are several special headers that help to indicate the state of a request thats being sent. These special headers are described in the next table.
Header |
Description |
|---|---|
X-SideFX-Retry-Num |
Indicates the number of retries for the event. If its the events first try this header is not included in the request. |
X-SideFX-Retry-Reason |
Indicates the reason for the retry. The various reasons a request can fail are described in the next table. If its the events first try this header is not included in the request. |
There are several ways that a request can fail which is described in the following table.
Retry Reason |
Description |
|---|---|
http_timeout |
The HTTP request previously timed out. |
http_error |
The HTTP request errored on the previous attempt. |
too_many_redirects |
The previous request was redirected more then the max of two redirects. |
connection_failed |
The previous attempt failed to connect to the webhook server. |
ssl_error |
There was an ssl error on the previous attempt. |
unknown_error |
Catch all error that indicates an error occurred on the previous attempt but sesinetd doesn’t know why it failed. |
Payload ¶
Each request sent from the license server to the webhook server follows the same structure described below.
request
{ "event": {}, "event_time": 000000, "event_id": "E100", "type": "event_callback", }
Key |
Type |
Description |
|---|---|---|
event |
object |
The object that holds all the event specific information. |
event_time |
timestamp |
The timestamp the event occurred at. The timestamp is of the servers epoch. |
event_id |
string |
The id of the event that occurred. Each event has a unique id that can be used to identify the type. |
type |
string |
When receiving an event request from the license server this value will always be |
Webhook State ¶
The webhook state indicates its health and ability to send webhook events.
Status |
Description |
|---|---|
Active |
The webhook is operational and more then 90% of requests to the webhook server are responding successfully. |
Unstable |
The webhook is operating in an unstable fashion. Between 90% and 5% of requests to the webhook server are successful. |
Failed |
The webhook has failed. Less then 5% of requests to the webhook server are successful. The webhook has been disabled and no new events will be sent to the webhook server. The webhook must be manually re-enabled once the webhook server has been repaired. To re-enable the webhook use hkey or the public api. |
Disabled |
The webhook has been disabled. No events will be sent to the webhook server. The webhook must be manually re-enabled using hkey or the public api. |
Responding To Events ¶
The webhook server must respond to events in order for the system to consider the request successful. If sesinetd receives to many events that were considered a failed delivery the webhook will be disabled. Each request is given three seconds to respond before it fails with failure reason http_timeout described here. A request is considered a success if sesinetd receives a 200 HTTP response from the webhook server for the request.
Note
Sesinetd will not cache events that failed to be delivered or events that occurred while the webhook is disabled or in a failed state. These events will be lost with no way to retrieve them.
Turning off retries ¶
If the webhook server is having a hard time keeping up with events or the server would prefer sesinetd not retry sending the event you can indicate this through a special HTTP header. Include this special header in your non-200 HTTP response to turn off retries.
X-Slack-No-Retry: 1
When this header is included it indicates to sesinetd that this specific event should not be retried. All other events will be uneffected and will be retried if necessary.
Throttling ¶
The webhook does not currently support throttling.
Rate Limiting ¶
It’s important that we do not flood your server with events that you can’t keep up with.
Event deliveries max out at 30,000 requests per 60 minutes. If sesinetd reaches that maximum sesinetd will hault sending new events to your server for that hour. During that hour your server is rate limited sesinetd will send a rate_limited event every minute.
{ "type": "rate_limited", "minute_rate_limited": 1691771520 }
Key |
Type |
Description |
|---|---|---|
minute_rate_limited |
integer |
A rounded epoch time indicating the minute the server started rate limiting events. |
type |
string |
When receiving a rate limited event the type will be |
Editing the Webhook ¶
Any user can view the webhook and the event subscriptions. Only users that have administrative permissions can edit the webhook url and the subscriptions.