Webhooks are a tool for retrieving and storing data from a certain event. They allow you to register an http:// or https:// URL where the event data can be stored in JSON format. Webhooks are commonly used for updating completion data in another system.
If you would otherwise have to poll for a substantial amount of data using the API, you should be using webhooks.
Webhooks can be registered for the following events:
We have plans to add support for more events.
At the moment, you need to contact Firmwater support to create or delete a webhook.
Please specify the following information:
Once you register a webhook URL with Firmwater LMS, we will issue a HTTP POST request to the URL specified every time that event occurs. The request's POST parameters will contain JSON data relevant to the event that triggered the request.
Webhooks can be verified by calculating a digital signature. Each webhook request includes a X-Firmwater-Lms-Hmac-Sha256 which is generated using the shared secret, along with the data sent in the request.
To verify the request came from Firmwater LMS, compute the HMAC digest according to the following algorithm and compare it to the value in X-Firmwater-Lms-Hmac-Sha256 header. If they match, you can be sure that the webhook was sent from Firmwater LMS and the data has not been compromised.
Below is a simple example in C# of how one might verify a webhook request.
Your webhook acknowleges that it received data with a 200 OK response. Any response outside of the 200 range will let Firmwater LMS know that you did not receive your webhook. We wait 5 seconds for a response to each request, and if there isn't one, we time out. To make sure that you don't run over the timeout limit, we recommend that you defer processing until after the response has been sent.
Automatic retries are planned for failed webhooks and requests that time out.
Webhooks require a publicly visible URL to handle them since they originate directly from the server. This means that you cannot use 'localhost' or fake domains like 'www.example.com' as an endpoint in your testing environment.
Fortunately, there are a couple tools that make working with webhooks during development much easier such as RequestBin, Pagekite, and ngrok.