Webhooks
Webhooks bring efficiency and responsiveness to solution architectures, facilitating event-based flows among applications and services. In Socotra Enterprise Core, they are customized callbacks that allow external services to receive real-time notifications when specific events occur. This functionality enables seamless integrations that can react to changes as quickly as possible.
Managing Webhooks
You create a webhook with a POST
request to the Create Webhook endpoint, specifying the URL and event types that pertain to the webhook. The endpoint will then receive an EventResponse payload whenever the relevant event occurs. Webhooks and the Event Stream share the same EventResponse structure to describe an event.
Failure Handling
You can define a failure handling strategy for each webhook, ensuring that the system responds in a preferable way if it encounters a problem posting messages to the webhook endpoint. Strategies revolve around these questions:
For which errors should the failure handling strategy apply?
Should an endpoint (
alertEndpoint
) receive failure notices?Should the platform automatically retry on message delivery failure? If so, how many attempts (
1
to10
, default3
), and what should the time interval and pattern be (linear
orexponential
)?Should the platform persist messages that fail to be delivered? These can be retrieved later via the Diverted Events API.
If no failureHandling
is specified, the default strategy will apply:
"failureHandling": {
"triggers": [
"4xx",
"5xx",
"timeout"
],
"divert": false,
"suspend": false
}
The default specifies no retry strategy or alert endpoint and does not automatically suspend the webhook, nor does it divert failed messages for later pickup via the Diverted Events API. It effectively means “behave with indifference as to whether message delivery succeeds”.
The triggers
array can be populated with specific 400- or 500-level HTTP codes, or all in those levels ("4xx"
, "5xx"
). The special keyword "timeout"
is also recognized.
If suspend
is set to true
, it means that the webhook will be suspended automatically if it exhausts all retry attempts while trying to deliver a message. If no retry strategy is specified, no retry attempts will be made, and the webhook will be suspended following the first failure. Webhook suspension will result in an event being posted to the alertEndpoint
if one has been configured, and subsequent messages diverted if the divert
property is set to true
. Webhooks can be unsuspended with the unsuspend endpoint endpoint.
When defining a retry strategy, you may set the type
to linear
or exponential
. While linear
results in a request being made at a constant frequency specified by the interval
(in milliseconds), exponential
means that the wait period between retry attempts will grow as defined in the equation {interval}} + {attempt}^4
.
See Also
Events: List of events and data structures
Webhook API reference: Details on creating, reading, listing, updating, and deleting webhooks