Webhooks

The Lessonspace API provides various webhooks you can use to get information about Spaces in real-time.

Setting up Webhooks

You can set up your own webhooks by specifying them in the body of your POST request to the Launch endpoint. Any webhooks sent on subsequent calls for the same Space (as identified by the id) will fully overwrite existing ones; they will not be merged in. This allows you to remove webhooks by passing a null value or empty string. You can leave webhooks as-is by simply not sending a new webhooks property.

See Adding Webhooks for an example.

The webhooks are defined as follows:

{
  "webhooks": {
    "session": {
      "start": "<endpoint-url>",
      "end": "<endpoint-url>",
      "idle": "<endpoint-url>"
    },
    "user": {
      "join": "<endpoint-url>",
      "leave": "<endpoint-url>",
      "idle": "<endpoint-url>"
    },
    "chat": {
      "message": "<endpoint-url>"
    },
    "cobrowser": {
      "start": "<endpoint-url>",
      "stop": "<endpoint-url>"
    },
    "transcription": {
      "finish": "<endpoint-url>"
    }
  }
}

Retries & Ordering

If your server returns a status code outside the 200 - 299 range, or takes longer than 30 seconds (including connection and response time), the webhook delivery will be considered a failure and retries will begin.

The retry algorithm uses an exponential backoff, and will attempt to deliver a payload up to 5 times. In order to not count retry delay in statistics, you can use the x-webhook-timestamp header, described below.

Events are guaranteed to be delivered in-order on a per-space basis and per-URL basis, with a single exception for the case of all retries failing. In that case, subsequent events will still be delivered.

Headers

Four custom headers are included with each delivery. These are:

• x-webhook-id Uniquely identifies the webhook payload. Retries use the same value.
• x-webhook-event The type of event being dispatched.
• x-webhook-timestamp An ISO8601 timestamp specifying when the webhook event took place.
• x-webhook-signature A cryptographic signature for security and authentication.

Security

The x-webhook-signature header allows you to both authenticate that the request originates with Lessonspace (as only you and Lessonspace know the secret key) and also verify that the payload has not been modified. The signature is calculated as an HMAC (using the sha256 algorithm) of the webhook payload as stringified JSON (generated with JSON.stringify() in Node.js), using the space secret as the signing key.

If the payload is stringified using a similar operation in another language, such as json.dumps in Python, note that the semantics of JSON.stringify mean that all unimportant whitespace is automatically removed from the final string. For Python, an equivalent operation would be json.dumps(x, separators=(',', ':')).

It is not sufficient to simply copy-paste the payload and quote it to create a string.

Events

User Events

webhooks.user.join

Triggered when a user joins a Space. This happens when the user opens their web browser to the Space URL and joins the lobby.

webhooks.user.idle

Triggered when a user is considered idle in a space. See Idle under Terms & Concepts for more information.

webhooks.user.leave

Triggered when a user leaves a space. This can occur when they close their browser tab, click the End Session button, or are otherwise disconnected.

All the above user webhooks share the same payload schema:

{
  "session": {
    "id": "internal identifier of the session"
  },
  "room": {
    "id": "internal identifier of the space"
  },
  "socketId": "internal socket id of the user",
  "user": {
    "id": "identifier of the user",
    "guest": "boolean flag indicating whether or not the user joined while signed in",
    "readOnly": "boolean flag indicating whether or not the user was in read only mode",
    "allowInvite": "boolean flag indicating whether or not the user had access to the Invite Others button",
    "meta": "...",
    "page": null,
    "av": "..."
  },
  "nbf": "...",
  "exp": "...",
  "canLead": "boolean flag indicating whether or not the user can lead",
  "traceId": "..."
}

Session Events

webhooks.session.start

Triggered when a space registers its first user join.

Payload Schema

{
  "id": "internal identifier of the session",
  "room": {
    "id": "internal identifier of the space"
  }
}

webhooks.session.idle

Triggered when all the users in a space are considered idle.

Payload Schema

{
  "id": "internal identifier of the session",
  "room": {
    "id": "internal identifier of the space",
    "allUsersIdle": true,
    "becameIdleAt": "ISO8601 date string indicating the datetime that the session became idle"
  }
}

webhooks.session.end

Triggered when a space registers its last user leave, or timeouts have been reached.

Payload Schema

{
  "id": "internal identifier of the session",
  "room": {
    "id": "internal identifier of the space",
    "allUsersIdle": "boolean indicating whether or not all users are idle",
    "becameIdleAt": "ISO8601 date string indicating the datetime that the session became idle"
  },
  "summary": {
    "start": "ISO8601 date string indicating start datetime of the session",
    "end": "ISO8601 date string indicating end datetime of the session"
  },
  "reason": {
    "state": "ended",
    "extra": "empty"
  }
}

Chat Events

webhooks.chat.message

Triggered when a chat message is sent.

Cobrowser Events

webhooks.cobrowser.start

Triggered when a Cobrowser activity starts in a session.

webhooks.cobrowser.stop

Triggered when a Cobrowser activity stops in a session.

Transcription Events

webhooks.transcription.finish

Triggered when a session finishes being transcribed.

Payload Schema

{
  "transcriptionUrl": "<pre-signed S3 URL>"
}