To configure a webhooks definition profile, you must have the following role:
- General System Administrator
Webhooks are user-defined HTTP callbacks that are usually triggered by some event, and include information on the results or status of that event.
Alma is able to send a webhook when one of the following occurs:
- A job run has finished running (using either the Alma UI or an API).
- A user is updated.
- One of the following notifications is sent:
Webhooks for these letters must be activated in the Letter Activity code table. For detailed information on these webhooks, see https://developers.exlibrisgroup.com/alma/apis/xsd/rest_webhook_notifications.xsd.
- Ful Cancel Request Letter (letter code: FulCancelRequestLetter)
- Borrowing Activity Letter (letter code: FulUserBorrowingActivityLetter)
- Loan Status Notice (letter code: FulItemChangeDueDateLetter)
- On Hold Shelf Letter (letter code: FulPlaceOnHoldShelfLetter)
For more information on webhooks, see the Developer Network.
In order for a webhook to be activated, Alma must have a webhooks integration profile configured.
To configure a Webhooks type of integration profile:
- On the Integration Profile List page (Configuration Menu > General > External Systems > Integration Profiles), select Add Integration Profile. The first page of the integration profile wizard opens.
- From the Integration type drop-down list, select Webhooks and enter a code and name for the profile.
- Select Next. The second page of the wizard opens.
Webhooks Integration Profile
- Select Activate to activate the webhooks integration profile. Until the profile is activated, the status reads Pending activation.
- Enter the listener URL for the Webhook Listener URL and secret code in Secret. For information on the values to be entered here, see the Technical Information table in Webhooks.
- Select whether the message type should be XML or a JSON.
- Under Subscriptions:
- Select Job finish to send a webhook when a job run has finished running (using either the Alma UI or an API).
- Select Notifications to send a webhook when one of the following notifications is sent: FulCancelRequestLetter, FulUserBorrowingActivityLetter, FulItemChangeDueDateLetter, FulPlaceOnHoldShelfLetter. Select Configure Notification Types to activate the webhooks for these letters in the Letter Activity code table. For detailed information on these webhooks, see the Developer Network.
- Select Users to send a webhook when user information is updated. This includes all user changes for which history is registered, including changes made by the Users job. Note that user changes using an API do not cause a webhook to be sent. In the User groups box, select the the user groups that will trigger a webhook to be sent. If no user groups are specified, a webhook will be sent for all user groups.
- Select Requests to send a webhook when a hold, booking, move, digitization, or work order request is created, closed, or placed on the hold shelf.
- Select Loans to send a webhook when a loan is created, returned, or declared lost.
- Select BIB records to send a webhook when a BIB record is changed.
- Select Physical items to send a webhook when a physical item is changed.
- Select Save. The profile you configured appears in the Integration Profile List.
- After the integration profile has been defined, you can select View Log from the list of integration profile actions. This option enables you to view a log of webhook events. The URL and payload elements of the table may then be searched.
- If webhook attempts fail, emails are sent to all the email addresses stipulated in the Webhooks profile's Contact Information tab.
- In Premium Sandbox environments, all the Subscription boxes are cleared automatically, effectively deactivating the integration profile. This is because the webhook actions that take place in the Sandbox environment land on the listener server the same as production data, which results in mixing test data and production data. If you want to activate the integration profile on a Sandbox environment, select the relevant subscriptions on this page and proceed as instructed in step 7 above.