API tweaks: endpoint overrides and hooks

Where to find it

Administration module, Import/Export screen, API tweaks section, API button.

The screen is reserved for Premium accounts and protected by reinforced authentication: Omniscol asks for the administrator's password again before opening the window. Since every action on this screen touches the technical contract of your integration, it is set up in coordination with Omniscol.

General configuration

Here you define HTTP headers (format key1:value1;key2:value2) applied to all hooks. It is the natural place to carry an authentication token to your own server (for example an Authorization: Bearer … your server expects). For an override, authentication goes instead in the headers specific to the endpoint (see below).

Overriding an endpoint

An override redefines an endpoint of the Omniscol API so that the web application calls another URL in its place. Three use cases, from the most powerful to the simplest.

Serving live data from your information system

This is the most powerful use case. You redirect a read endpoint to an external URL — typically an ETL that interfaces with your institution's internal information system. The web application then fetches the data live from that system, instead of the local copy held by Omniscol.

In practice: when the redirect URL is an absolute external address, the web application calls it directly, without going through Omniscol's servers, and consumes the response as-is — exactly as if it came from Omniscol. The only constraint is that your system responds in the format Omniscol expects for that endpoint (same JSON structure): there is no intermediate transcoding. For that endpoint, Omniscol's local copy is not queried; the data displayed is the live data of your system.

Example: the institution's subject catalog served on the fly from your information system, so that any update on the school side is immediately visible in Omniscol, without a re-import.

Authentication to your system goes here in the headers specific to the endpoint (for example an Authorization: Bearer …), entered on the override's row. The HTTP method can also be enforced per endpoint.

Rewiring an endpoint of the application itself to a live external source is a possibility as powerful as it is demanding: to be handled with your IT department, and in coordination with Omniscol.

Inserting your own server or a proxy

You can also route the calls through your own server or a proxy — for example to allow cross-origin resource sharing (CORS), or to insert in-house logic between the web application and Omniscol.

Disabling an endpoint

You disable an endpoint by giving it no redirect URL (method null).

Weigh the effect on the interface. Omniscol is a single-page web application (SPA) whose interface elements are driven by the available endpoints: buttons, tabs and menus only appear if the endpoint they depend on exists. Disabling an endpoint therefore dynamically removes, at the next refresh, the interface elements that depend on it — and if you disable all the endpoints of a module, the entire module disappears from the navigation. These elements are removed, not merely hidden, and all of this happens without any change to the code: just edit the configuration and reload the application.

The table lists, per endpoint: its key (the internal code of the operation), its original URL, the HTTP method, the new URL of the redirect and specific headers. A search field lets you find the endpoint to override.

Hooks (outbound calls)

A hook asks Omniscol to send an HTTP request to your URL after an operation has succeeded. It is the mechanism for keeping an external system informed in real time — a display panel, a digital workspace, a human resources system, an in-house synchronization…

A hook can be attached in two ways:

• to a specific endpoint (the operation's key);
• to a grouped event, which covers a whole family of operations at once. Three grouped events exist:
  • timetable change (creation, move or deletion of lessons, activation of a timetable, and teacher or class absences as soon as a date is affected);
  • teacher change (addition, update or deletion);
  • subject change (custom subjects).

For each hook, you fill in the callback URL, the HTTP method, the "with data" checkbox (should the original request body be attached?) and its own headers.

What your server receives

The call is sent as application/json and carries, in addition to your headers:

• the body of the original request if the "with data" option is enabled;
• a block of Omniscol metadata: the called URL, the endpoint code, the method, the parameters, the user's authentication token and the school identifier;
• traceability headers: X-OS-original-query, X-OS-original-endpoint, X-OS-auth and X-School.

For the timetable change event, when the "with data" option is active, the call additionally includes a diff of the lessons (lessons added, changed, deleted) — handy for propagating only what has changed.

Behavior

Hooks fire in the background, after the user's operation has completed: they do not slow down the interface and do not block it if your server fails. An outbound call that does not go through is logged, without interrupting work in Omniscol. Each call has a short timeout (a few seconds): your server must acknowledge receipt quickly and process the rest on its side.

Good to know

• The Omniscol API exposes a subset of operations; an override or a hook only applies to the endpoints actually exposed. See Omniscol API for the list and authentication.
• For an integration with a software package (ERP, HR system, digital workspace), the dedicated synchronization is often a better fit — see Synchronization with external systems. Internally, the same hook system is used.
• For an AI agent to read your data without any development, see MCP — connect an external AI agent.