Webhooks

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.

Webhook events

Webhooks can be registered for the following events:

Training activity completedThis event occurs each time a participants completes an activity.

The event data consists of a PersonItemStatus object for the participant and activity.
Training assessment attempt completedThis event occurs each time a participant completes an attempt at an assessment served out by Firmwater LMS's built-in assessment engine.

The event data consists of an AttemptStatus object for the participant's attempt.

We have plans to add support for more events.

Creating webhooks

At the moment, you need to contact Firmwater support to create or delete a webhook.

Please specify the following information:
  1. Event
  2. URL
Once created, we will provide you with a shared secret.

Receive a webhook

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.

public bool VerifySignature(NameValueCollection headers, string secret, string postData)
{
    var signature = headers["X-Firmwater-Lms-Hmac-Sha256"];
    if (string.IsNullOrEmpty(signature))
        return false;

    using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
    {
        var stream = new MemoryStream(Encoding.UTF8.GetBytes(postData));
        var hash = Convert.ToBase64String(hmac.ComputeHash(stream));

        return hash.Equals(signature);
    }
}

Respond to a webhook

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.

Testing webhooks

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.