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.

Enriching events

Webhook events do not contain data that personally identifies our users. If your webhooks integration requires PII data, it is possible to enrich events by calling our GraphQL API with the user's ID.
The following code snippet shows how to fetch a user's email address using.
1
query GetEmail(userID: String!) {
2
user(userID: $userID) {
3
profile {
4
email
5
}
6
}
7
}
Copied!
You cannot retrieve email addresses of users which haven't claimed one of your organization's track invites

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
1
{
2
"challenge_id": "dxhrbpuvvia9",
3
"completed": true,
4
"invite_id": null,
5
"organization_id": "instruqt",
6
"participant_id": "tncb0s7cdkyu",
7
"timestamp": "2021-07-29T16:14:57.31297754Z",
8
"track_id": "rzwlxtp92ted",
9
"track_slug": "getting-started-with-instruqt",
10
"type": "track.challenge_attempted",
11
"user_id": "gOGhYjyoPJhINJFOugIgiL4pdzu2"
12
}
Copied!

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
track_slug
The track URL 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.
challenge_index
The index of the current challenge.
total_challenges
The total number of challenges for a track.

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
Last modified 13d ago