DreamClass API

Overview

View as Markdown

Overview

This API provides webhooks to notify external systems upon certain events. The event data is represented by the JSON payload included in the request body. Optionally, the outgoing request can use Basic Authentication for security. Additionally, each request may contain a HMAC hash for request validation. Finally, this API is supplementary to the DreamClass API, meaning that the entities returned by this API can be used as input to the DreamClass API to retrieve more data.

Configuration

In the DreamClass app, under Settings > Integrations you can configure the webhooks functionality

  • URL: The (http/https) url that will be used for the outgoing requests.

  • Username / Password: Optionally, set the Basic Authentication credentials for the outgoing requests.

  • Secret: Optionaly, set the HMAC key to be used for the signature generation.

  • Events: Select the events that should trigger a webhook.

HMAC Validation

Each request contains a signature attribute, which includes the hashed value of the request ID calculated using HMAC with the specified secret key. The server should validate this signature to ensure the request’s integrity.

  • HMAC Algorithm: HmacSHA256

  • Key Encoding: Base64

Sample request

1{
2   "tenant":"my-school",
3   "timestamp":1727862002901,
4   "id":"b3e6fa78-8672-4e8b-8431-7eebdabd25a2",
5   "signature":"nGq8sspzZVWObaR4zUOLyQ29m/IBxxD716hKx5298No=",
6   "type":"STUDENT_PERIOD_CREATED",
7   "data":{
8      "id":32,
9      "active":true,
10      "studentId":76,
11      "addedAt":"2024-10-02T09:40:02.179+00:00"
12    }
13}

  • id: The ID of the request.

  • signature: The HMAC hash of the ID.

  • type: The event type.

  • tenant: The DreamClass domain.

  • timestamp: The timestamp of the request.

  • data: A JSON document that contais event data.

Response

The response to the webhook should be HTTP 200; otherwise, it will be marked as failed. The HTTP request must be completed within 10 seconds. Failed request are retried 3 times before being discarded.