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

There are two main benefits of using webhooks:
  • 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

You can read more about Webhooks in the Tech Blogs.

READ MORE IN THE BLOGS

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.

Supported Events

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

Supported Protocols & Formats

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

Note: SSL connections must be secured with a certificate issued by a recognized certificate authority. See the list here.

Security

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.

Required Endpoints

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.

Request Payload

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.

Response Codes

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

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

Retries mechanism

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.