Ready to Learn?Ex Libris products all provide open APIs

Webhooks

 
 
Webhooks are "user-defined HTTP callbacks". They are usually triggered by some event, and include information on the results or status of that event. When that event occurs, the source site makes an HTTP request to a configured URI. The target end-point catches the HTTP call, and might take an action according to the received information.
There are two main benefits for webhooks:
  • Efficient programming - applications and scripts which can be called when needed, rather than having to pull for work
  • Efficient use of APIs - use fewer API calls to enable additional integration scenarios without reducing from the daily API threshold
 

Alma is able to send a webhook when the following occur:
  • A job run has finished
  • Notification is sent
  • User Updated 
  • Loan events 
  • User request events
  • BIB events
  • Item events

 

Technical information

Technical informationDescription
supported protocolHTTPS
Note: SSL connections must be secured with a certificate issued by a recognized certificate authority. See the list here.
supported formatsXML, JSON
security policyYou 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.
URL
  • challenge message: GET {Webhook listener URL}?challenge={random text}
  • webhook messages: POST {Webhook listener URL}
message content (as payload)webhook - see Supported types below for details
expected end-point response
  • 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 pick hours webhooks might not be sent immediately.

 

Supported types

Alma is able to send a webhook when the following occur (the Event Name column represents the value of action field in the webhook structure):

Event NameDescriptionBody payload
JOB_END

When jobs in the system are completed, either successfully or with errors.

This webhook is sent for both manual and scheduled jobs, for jobs triggered in Alma UI or by API.

rest_job_instance
NOTIFICATIONWhen one of the following notifications is sent: FulCancelRequestLetter, FulUserBorrowingActivityLetter, FulItemChangeDueDateLetter, FulPlaceOnHoldShelfLetter.
Webhooks for these letters must be activated in the Letter Activity mapping table.
rest_webhook_notifications
USER

When user information is updated. This includes all user changes that keep audit, including changes by SIS or the update-user job.
Note that user changes by API do not cause a webhook.
It is possible to define (on the Webhook integration profile) which user groups will trigger the webhook. If not specified - all user groups will be included.

webhook_user_extended
LOANWhen the following loan related events occur:
  • Loan created
  • Loan returned
  • Loan has been declared lost
  • Loan has been claimed returned
  • Loan renewed
  • Loan due date has changed

The specific event will be specified in event field of the webhook structure.

rest_item_loan
REQUESTWhen the following user request related events occur:
  • Request created
  • Request closed
  • Request placed on shelf
The specific event will be specified in event field of the webhook structure.
Note that requests of the following types are included: HOLD, BOOKING, MOVE, DIGITIZATION, WORK_ORDER.
rest_user_request
BIB

When BIB information is updated.
The specific event will be specified in event field of the webhook structure.

rest_bib
ITEM

When item information is updated.
The specific event will be specified in event field of the webhook structure.

rest_item
 
 
 
In order to trigger a webhook in the above events, the "SUBSCRIPTIONS" section of the Webhook integration profile should be configured. For example:

This section defines which events of the above types will trigger webhooks. Fore details regarding the Webhook integration profile, see Alma OLH.
 

Configuration and setup

To enable webhooks in Alma, the following is required:

  1. Create an HTTPS endpoint which Alma will call with the relevant information.
  2. Configure a “Webhook” integration profile in Alma, see Online Help.

Note that in order to activate the integration, Alma will send a “challenge” message.
Your HTTP end-point should response to this message with the text of the “challenge” parameter, in JSON.
For example, the challenge message is GET {Webhook listener URL}?challenge={random text}. The response should be 200, with the following as a payload: {challenge: “random text”}

The following diagram illustrates the workflow:

See related blog entries.