EdisonOS
11. Integrations

11.5 API & Webhooks Docs

Updated 5 months ago

This feature is available only for Enterprise Plan

The Docs tab, under Settings ā†’ API & Webhooks ā†’ Docs, is the technical manual for the EdisonOS API and webhooks. The other two tabs are where you click buttons to set things up; this is where the technical details live.

What the Docs tab is

The Docs tab is read-only and built into the product, so it always matches the current version of the system there's no separate docs site to keep in sync.

It's written for whoever is building the integration: an in-house developer, a contractor, an agency, or whoever maintains your Zapier/Make/n8n flows. As the Owner or Admin, you don't need to read it cover-to-cover. Your job is to know what's in there so you can point your developer to the right section.

How it's organised

The page has a sidebar on the left and a scrollable main panel. The sidebar has two sections:

  • API Reference - sending data to EdisonOS.

  • Webhooks Reference - receiving data from EdisonOS.

Click any subtopic in the sidebar to jump to that part of the docs.

API Reference

Subtopic

What it covers

Base URL

The single web address all API requests go to: https://gateway.edisonos.com. All traffic is HTTPS.

Authentication

How to pass the access token using the X-API-Key header, and what each token status (Active / Paused / Revoked) means.

Errors

The standard JSON error format (message, error_code, details) and the full list of error codes ā€” VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, ACADEMY_NOT_FOUND, RATE_LIMIT_EXCEEDED, INTERNAL_ERROR.

Endpoints

The actual actions available. Currently one: POST /students/enroll.

The Endpoints subtopic for POST /students/enroll includes:

  • Request body - a students array of 1ā€“50 objects, each with full_name, email, and programs.

  • Program labels - sat, act, psat_nmsqt, psat_10, psat_8_9, shsat, isee, ssat, ap_us_history, ap_physics_1.

  • Example request and response as copy-paste JSON.

  • Behavior notes - existing students (matched by email) get enrolled into any new programs, duplicates are skipped, and the whole batch fails if any single student is invalid.

Webhooks Reference

Subtopic

What it covers

Overview

How webhook delivery works at a high level.

Events

The events you can subscribe to. Currently assessment.summary.

Delivery

The headers EdisonOS sends with each webhook, the retry policy (6 attempts, 2sā†’5min backoff), the 10-second timeout, and what status codes your server should return.

Verifying Signatures

The exact format of X-Edison-Signature and step-by-step verification, with Python and Node.js code samples ready to copy.

Payload Format

The full JSON structure of assessment.summary, field by field with student info, assessment metadata, summary scores, section breakdowns, per-question results with timing and tags.

Best Practices

Four practical tips: respond quickly with 2xx, deduplicate using X-Event-Id, always verify signatures, and avoid logging student personal data.

Handing off to a developer

A clean handoff usually looks like this:

  1. In the API tab, create an access token named for the project (e.g. enrollment-sync-prod). Copy the value once and save it in your password manager.

  2. In the Webhooks tab, add the webhooks you need. Copy each signing secret once.

  3. Share the token and signing secrets with your developer through a secure channel includes password manager, encrypted vault, or short-lived secure note. Don't use email or chat.

  4. Send them the link to the Docs tab. Everything else they need is in there.

For staging vs production, create separate tokens and webhooks per environment (-staging, -prod). Never share tokens across environments.

If your developer hits something the Docs tab doesn't cover, contact EdisonOS support with the request method, path, request body (with the token redacted), and the response. That's usually enough for us to help quickly.

Was this helpful?
Was this helpful?