DreamClass API

Overview

View as Markdown

These are requests DreamClass sends to you. You register a URL under Settings > Integrations and DreamClass POSTs to it whenever data changes. The pages in this section document the payload you will receive; the URL shown on each one is a placeholder for your own endpoint, not a DreamClass address.

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 receive the outgoing requests.

  • Username / Password - optional Basic Authentication credentials for the outgoing requests.

  • Secret - optional HMAC key used to generate the signature.

  • Events - 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

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

  • 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 contains 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 requests are retried 3 times before being discarded.