Overview

A webhook pushes a JSON payload to a URL you own each time something happens in a lab session: a session starts, a sandbox is provisioned, a learner completes a task.

Use them to record learner progress in an LMS, prospect activity in a CRM, or to trigger automation without polling the API.

Add an endpoint

An endpoint is a publicly reachable URL that Instruqt delivers events to. Endpoints belong to a team and receive events for every lab on that team.

Adding one needs the team webhook administrator permission.

1. Open Settings → Webhooks.
2. Click Add Endpoint.
3. Enter your Endpoint URL, or click with Svix Play to try it without writing code.
4. Optionally add a Description.
5. Under Subscribe to events, select the event types this endpoint receives.
6. Click Create.

Note

Endpoint URLs must be publicly accessible. Instruqt cannot deliver to a URL behind your VPN or firewall.

Subscribe to events

Subscribe to events groups the types by family. Tick the lab group to receive every lab event, or expand it and tick individual types. The event reference explains what each one means.

Selecting nothing receives everything

With nothing selected the form reads Receiving all events, and the endpoint receives every event type, including ones added later. Either select the types you want, or make your handler ignore types it does not recognise.

Try it without writing code

On the New Endpoint form, click with Svix Play next to the URL field. It fills in a throwaway URL that captures deliveries in your browser, so you can start a lab and read real payloads before building a handler.

Caution

A Svix Play URL is unauthenticated. Anyone with the link can read everything delivered to it.

See what was delivered

The tabs at the top of the Webhooks page:

• Endpoints — your endpoints, with the error rate of each.
• Event Catalog — every event type and the schema of its payload.
• Logs — every delivery attempt, successful or failed, with the payload and the response. You can replay a delivery from here.
• Activity — a chart of recent delivery attempts.

Change or delete an endpoint

Open Settings → Webhooks and click the endpoint. From its page you can change the URL, the description, and the subscribed events, or delete the endpoint.

Verify that an event came from Instruqt

Your endpoint is public, so anyone who learns the URL can post to it. Instruqt signs every webhook with a key unique to the endpoint. Verify that signature before you act on a payload.

The signature is in the svix-signature header, and the endpoint’s signing secret is on the endpoint’s page. Follow this guide to verifying payloads, which has libraries for most languages.

Delivery

• Respond with a 2xx quickly. Acknowledge the delivery and do your own work afterwards. A failed delivery is retried over a backoff schedule, and repeated failures can get the endpoint disabled.
• Expect the same event more than once. Delivery is at-least-once. Deduplicate on session_id, type, and activity_id where the event has one, and make your handler safe to repeat.
• Handle event types you do not recognise by ignoring them.
• An event can be lost. Delivery is not guaranteed, and a lost event leaves no error. Do not make webhooks your only record of something that must be right — reconcile a certificate, a grade, or an invoice against the Instruqt API.

Payloads carry no personal data

Payloads identify people and content by identifier only. They never carry a name, an email address, or an IP address.

If you need personal data, resolve it from the identifiers in the payload — user_id, and invite_id where the session came from an invite — through the Instruqt API.