Skip to main content
U.S. flag

An official website of the United States government

Web Hooks for ADL's Open Source LRS

January 14, 2016

If you have built any client reporting applications powered by Experience API (xAPI) statements, you know the workflow consists of the client first pulling statements from a Learning Record Store (LRS), then parsing and displaying the data. We’re currently implementing and testing webhooks for the open source (i.e., free!) ADL LRS, which would eliminate the step of pulling statements first. Instead, clients would listen for statements being pushed to them from the LRS.

Webhooks are a way to register client applications that are interested in certain sets of statements. Every webhook that is registered contains the client endpoint as well as filters that dictate what kind of statements the client wants the LRS to send. For example, if a client only wanted statements where the verb was “Completed” and the object was “Course x”, it would register a webhook that listed the “Completed” verb under the verb field and “Course x” under the object field along with a URL to send the statements. Our LRS project at GitHub now has a separate branch called ‘Webhooks’ that contains the updated code and is available to everyone.

Here’s a quick look at how they work:

  1. The LRS user creates a hook that includes the client address to receive statement(s) and its statement filters.
  2. The LRS receives statement(s). It cycles through each saved webhook and sees if the current received statement(s) match the filter criteria.
  3. If any of the statement(s) match the criteria, the LRS will send those statement(s) to the client endpoint that was supplied.

Please visit our wiki for examples and more in depth reading about our webhooks and API

Please note that since this is still in the experimental phase, we’re not expecting everything to run perfectly. The way it currently works is that with every incoming statement POST/PUT, the LRS looks at all of the hooks and their filters and determines if it should send the statements out to the endpoint. Eventually we could have batching functionality where clients can say they only want statements pushed daily, hourly, etc. The LRS would then keep all incoming filtered statements in a queue up to the point of the scheduled batch and send them off when the time came. Another feature we’d like to implement is a limit of requests the LRS can make. LRS servers with limited capabilities would be able to count how many batches they push out per day to limit the number of tasks being created.

If you have any questions/comments/concerns, please visit the LRS GitHub page and let us know!