Webhooks

Alma supports webhooks to enable the efficient processing of events which occur with the system.

Webhooks are “user-defined HTTP callbacks.” They are usually triggered by some event… When that event occurs, the source site makes an HTTP request to the URI configured for the webhook.

Wikipedia

• Efficient programming – applications and scripts which can be called when needed, rather than having to poll for work
• Efficient use of APIs – use fewer API calls to enable additional integration scenarios

In the diagram below we see a typical webhook use case. On the left we poll with APIs to find out when a job has been completed. On the right we ask Alma to notify us via webhook when the job was completed so that we can continue our orchestration flow.

For a list of events which support webhooks, see here.

Webhooks are sent via HTTPS only. The body can be either JSON or XML.

Notes:

• The requests are sent with a defined timeout of 5 seconds. If the request took more than that, it is considered as if a 500 HTTP error was returned and is retried (see Retries mechanism below).
• SSL connections must be secured with a certificate issued by a recognized certificate authority. See the list here.

You should generate a “secret”, and configure it as part of the Alma integration profile (see Alma OLH). Alma will use this secret in order to sign the webhook messages (HMAC using SHA-256 cryptographic hash function -encoded to Base 64). Note that the initial challenge message is not signed.

Two endpoints are required to be implemented by a webhook listener.

Challenge message:

GET {listener_url}?challenge={random_text}

Webhook messages:

POST {listener_url}

For more information see Anatomy of a Webhook.

Alma will send a request based on the webhook object. The payload will include an object specific to the type of message sent according to the list here.

Endpoints are expected to respond with one of the HTTP response codes below:

• 200 in case of success
• 4XX in case of logical failure

If 5XX HTTP response is received, Alma will try to send the webhook message again after 1 hour, 3 hours, 6 hours (total of 10 hours between the first and the 4th attempt). After a 4th failure of a specific webhooks call out, an email will be sent to all email contacts defined on the webhook integration profile.

Note that Alma sends the webhooks asynchronous to the updates in Alma’s DB, so at peak hours webhooks might not be sent immediately.

We attempt to send Webhooks from Alma as close as possible to when the event occurred. To facilitate this, we need to avoid cases where large number of requests are queued. Therefore, Webhooks will not be sent if the changes in Alma were triggered by a job handling more than 500,000 records at once. We recommend that after massive changes you synchronize via other means such as publishing.

In most cases, webhooks are sent near-real-time. While periods of unusual load may cause delays (perhaps as long as several hours), webhooks will eventually be sent for the relevant actions. You should take potential delays into consideration when designing your application.