11.4 Webhooks

This feature is available only for Enterprise Plan

Every request needs an access token so EdisonOS knows it's really coming from your academy. You'll find it under Settings → API & Webhooks → API.

While the API is how your tools ask EdisonOS to do something, a webhook is the opposite. It's how EdisonOS tells your tools when something happened. You'll find webhooks under Settings → API & Webhooks → Webhooks.

Tokens belong to the academy, not to the person who created them, so they keep working even after staff changes.

What you can do today

Right now, the API supports one action: enrolling students into programs.

Method	Endpoint	What it does
`POST`	`/students/enroll`	Enrolls up to 50 students into one or more programs in a single request.

More actions will be added over time. Full technical details are in the Docs tab.

Creating an access token

Open Settings → API & Webhooks and stay on the API tab.
Click + Add access token in the top right.
Give the token a clear name based on where it'll be used. e.g. website-signup, hubspot-sync, bulk-import. This helps later when you have several tokens.
Click create. EdisonOS shows the full token on screen.
Copy it immediately and save it in a password manager. Share it with your developer through a secure channel.

Every token starts with eos_ so it's easy to recognise.

You can only see the full token once, right after creation. EdisonOS never shows it again. If you lose it, revoke that token and create a new one.

Token statuses

Every token is always in one of three states:

Status	Effect
Active	Requests work normally.
Paused	Requests are temporarily blocked. Can be reactivated anytime.
Revoked	Requests are permanently blocked. Cannot be brought back.

New tokens are Active by default.

Pausing or revoking a token

Pause a token if you want to temporarily stop the integration without losing the token itself. Good for testing, debugging, or putting an integration on hold. The token stays the same, so reactivation needs no code changes.

Revoke a token when:

It's been leaked or accidentally shared (in a public repo, a screenshot, an email).
The integration is no longer needed.
The person or vendor who set it up is being offboarded.

Revoke is final. If you need access again, create a new token and update your integration.

Using the token in requests

Your developer passes the token in a header called X-API-Key on every request:


X-API-Key: eos_abc123...

A simple example using curl:


curl -X POST https://gateway.edisonos.com/students/enroll \
  -H "X-API-Key: eos_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"students":[{"full_name":"Jane Doe","email":"jane@example.com","programs":["sat"]}]}'

If something goes wrong, the response will explain why:

Status	Meaning
`401`	Token is missing or wrong.
`403`	Token is paused or revoked.
`429`	Too many requests so slow down and try again.

Keeping tokens safe

Tokens give write access to your academy's data, so treat them like passwords.

Store them in a password manager, never in plain files or shared docs.
One token per integration, named for its purpose. If one is leaked, the others keep working.
Don't paste tokens into emails, chat, or screenshots.
If a token leaks, revoke it immediately and create a new one.
All API traffic must go over HTTPS.