Webhooks

Integrate with third party systems through webhooks

Webhooks allow you to integrate Instruqt with third party platforms. This document explains the different use cases for webhooks, how to configure webhooks, and which events you can consume.

Configuration

Webhooks are in private beta. Please contact support if you are interested in using this feature.

To configure a webhook, navigate to your organization on the Instruqt platform. Here you will see a tab named "webhooks" (note: you require the owner role to be able to configure webhooks). To configure a new endpoint follow these steps:

  1. Click "Add Endpoint" and enter the URL which exposes your webhook consumer. (note: this URL should be publicly accessible).

  2. Select the event types you want to send to this webhook, leave empty if you want to send all event types to the webhook.

  3. Click confirm

On the logs tab you can view all events delivered, either successfully or failed, to your configured endpoints.

Verifying authenticity

Because your webhook endpoint is publicly available, anyone can impersonate the Instruqt platform by sending events to your endpoint.

In order to identify impersonated requests, Instruqt signs every webhook and its metadata with a unique key for each endpoint. You can use this signature to verify the event's authenticity.

This guide explains how to verify the event's signature.

Events

This section contains an explanation of all the events that the Instruqt platform can send to a webhook.

Example event

This is an example event for a challenge_attempt

{
"challenge_id": "dxhrbpuvvia9",
"completed": true,
"invite_id": null,
"organization_id": "instruqt",
"participant_id": "tncb0s7cdkyu",
"timestamp": "2021-07-29T16:14:57.31297754Z",
"track_id": "rzwlxtp92ted",
"type": "track.challenge_attempted",
"user_id": "gOGhYjyoPJhINJFOugIgiL4pdzu2"
}

Track Events

We send the following events for each track play:

Event Type

Description

track.started

A user starts playing a track

track.completed

A user completes a track

track.cleaned

The platform cleaned the sandbox

track.challenge_attempted

A user submits a challenge attempt

track.challenge_setup

The platform initialized a challenge by executing the setup script

track.challenge_completed

The user completed the challenge

track.challenge_started

A user starts a challenge

track.challenge_cleaned

The platform cleaned a challenge by executing the cleanup script

track.skipped_to_challenge

A user skipped to a challenge

track.stopped

A user or the platform stopped a track

Each event contains the following fields:

Key

Value

Type

track_id

The track identifier

string

organization_id

The identifier of the organization this track belongs to

string

timestamp

Instant the event occurred

string

participant_id

The identifier of this user's unique play of the track

string

invite_id

The invite the user claimed to gain access to this track, if any

string | undefined

user_id

The user identifier

string

mode

The current play mode

platform | embed | ci

custom_parameters

The custom parameters for this play

object | undefined

Additionally challenge events can contain the following fields:

Key

Value

challenge_id

The ID of the current challenge.

Sandbox events

We send the following events during the lifecycle of a sandbox.

Event Type

Description

sandbox.creating

The platform starts creating a sandbox

sandbox.created

The platform created a sandbox

sandbox.failed

The platform was unable to setup the sandbox

sandbox.cleaned

The platform cleaned the sandbox

Each event contains the following fields:

Key

Value

track_id

string

organization_id

string

timestamp

string

participant_id

string

invite_id

string | undefined

user_id

string

mode

platform | embed | ci

custom_parameters

object | undefined

Review events

We send the following events for track reviews:

Event type

Description

review.created

A user created a track review

review.updated

A user updated a track review

Each event contains the following fields:

Key

Value

Type

review_id

The identifier of this review

string

track_id

The identifier of the reviewed track

string

organization_id

The identifier of the organization this track belongs to

string

user_id

The identifier of the user leaving a review

string

score

The score

int

content

The written feedback, if any

string | undefined

Example: Sending events to Zapier

Zapier is a no code automation platform. You can send webhooks events to Zapier and integrate with other applications (e.g. Slack, Marketo, Google Workspace) without having to write any code.

Follow these steps to create a Zap from an Instruqt webhook:

  1. Create a new Zap

  2. Configure the Webhooks by Zapier trigger. (for more information)

  3. Select the Catch hook trigger

  4. After the previous step you will be presented with a webhook endpoint. Configure this endpoint in the Instruqt admin section.

  5. You can send a test event by starting a track in your organization.

  6. After the Zap has successfully received an event you can configure any Action you like