Webhooks

Overview

DigitalChalk Webhooks help developers more efficiently work with DigitalChalk through receiving HTTP callbacks when events occur within DigitalChalk. Webhooks can be configured to send HTTP POST or PUT requests to a custom endpoint. DigitalChalk Webhooks provide an easy way to integrate into your existing web services without having to poll DigitalChalk through the API. Webhooks originiate from the DigitalChalk underlying architecture in an asynchronous process and should not be confused with allowing a client-side redirect within the application.

Webhooks expose events which occur within your organization and can be configured through the DigitalChalk interface. The following Webhooks are currently supported:

Supported Webhooks

Offering Registered Event	Receive a webhook callback when a user is registered for an offering.
Offering Completed Event	Receive a webhook callback when a user completes an offering.
Element Published Event	Receive a webhook callback when an element is activated into a course.
Element Completed Event	Receive a webhook callback when an user completes a element they are taking within a course.
User Created Event	Receive a webhook callback when an user is created in the organization.

Configuring a Webhook

You can configure a webhook through the administrator interface within your DigitalChalk account. A webhook call from DigitalChalk must be to a URL using the http:// or https:// protocol to a publicly accessible URL. Because webhooks are meant to send data about a state change in the DigitalChalk system, they cannot be sent to a development machine that may sit behind a VPN or a server running at localhost like a local developement server.

Receiving a Webhook

Webhooks can use either the HTTP POST or PUT method depending on how you configure the webhook notification. The body of the request will include the JSON data relevant to the event firing the webhook. If you have chosen to recieve the request as a PUT request, be aware that not all servers come preconfigured to accept them. You may need to turn on that ability for your servers.

Responding to a Webhook

Your server should respond with an HTTP Status code in the 2xx range, preferrably a 200 OK status. If DigitalChalk does not receive a status code in the 200 range, or your servers do not respond within 5 seconds, it will be considered a failed webhook request.

In the case that DigitalChalk gets a failed webhook request, we will continue to try to make the webhook request for a total of 5 times over a 2 hour period. After that two hour period, we will cease to retry the webhook and it will be put into a failure state. Failed webhooks can been seen by the administrator within DigitalChalk and can be retried from the dashboard.

Security

Because webhooks by their nature will allow anyone who knows the endpoint of your servers to make calls into your application, we have added two layers of additional security that will allow you to refuse or ignore invalid requests. You can enable either BASIC or DIGEST Authentication for your server as well as calculate a digital signature for verification of the payload.

Authentication

When a site has implemented Authentication, visitors are prompted for a username and password. If the visitor does not provide valid credentials, they are rejected with a HTTP Status Code of 401. For webhooks in DigitalChalk, you will be able to provide those credentials ahead of time and when the webhook makes a request to your server, DigitalChalk handles the negotiation and credential passing to your secured endpoint.

BASIC Authentication Selecting Basic Authentication will allow you to specify a username and password as well as a realm for authentication.

DigitalChalk will first make the request to your specified URL endpoint in anticipation of an HTTP 401 Not Authorized Reponse with a WWW-Authenticate header. An attempt will then be made to authenticate and resend using the username, password and realm (if specified).

BASIC Authentication does not provide any encryption for the crednetials, so it is important that you specify an https protocol for your url for the best protection. You can read more on the specification here.

DIGEST Authentication Digest Authentication is a more secure alternative to basic authentication because passwords are encrypted before they are sent across the network. Digest Authentication will also allow you to specify a username and password as well as a realm for authentication.

As with Basic Authentication, DigitalChalk will first make the request to your specified URL endpoint in anticipation of an HTTP 401 Not Authorized Reponse with a WWW-Authenticate header. A Digest request for authentication will also send a “nonce” which is a token that is only valid for one request and in some cases a nonce counter and quality of protection. An attempt will then be made to authenticate and resend using the username, password and realm (if specified) in an encrypted form.

Although Digest Authentication is encrypted and more secure than Basic Authentication is it still important that you specify an https protocol for your url for the best protection. You can read more on the specification here.

Digital Signature

DigitalChalk will also provide a Digital Signature of the webhook in the request headers which will allow you to verify the webhook on receipt. The webhook signature is created by using your organizations webhook shared secret and signing the request body using the HmacSHA256 algorithm and then a Base64 encoding of that signature. This signature is pushed into the request headers under the name X-DigitalChalk-Hmac-SHA256. To verify the contents of the webhook came from DigitalChalk you can simply sign the payload in the same way on the receiving server and compare the signatures to make sure that they match.

Calculating a digital signature is not a required step for receiving a webhook request from DigitalChalk. The signature is simply included as a header in the request. This signature simply gives you an extra measure of protection if you choose to use it.

PHP Example

$s = hash_hmac('sha256', '{ "example" : "payload" }', 'ourlittlesecret', true);
echo base64_encode($s);

Java Example

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;

public class WebhookSignatureExample {
  public static void main(String[] args) {
    try {
      String secret = "ourlittlesecret";
      String payload = "{ \"example\" : \"payload\" }";

      Mac sha256HMAC = Mac.getInstance("HmacSHA256");
      SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
      sha256HMAC.init(secret_key);

      String result = Base64.encodeBase64String(sha256HMAC.doFinal(payload.getBytes()));
      System.out.println(result);
    } catch (Exception x){
      System.out.println(x.getMessage());
    }
  }
}