Timetabling Solutions is introducing Webhooks as a way to support better workflows in third party integrations. Webhooks is a concept in IT that enables event-driven software design by allowing clients to register their own publicly accessible HTTP endpoint for receipt of specific messages based on events at the server. This means that client no longer have to poll the server to monitor for changes, they can now sit back and wait to be told their data is ready.


Implementation

The Webhooks Api is split into three sets of endpoints:


Subscriptions

The subscriptions endpoints support the creation, management and removal of Webhook subscriptions for a specific event and URL.

MethodRouteDescription
GET/api/Webhooks/SubscriptionsList non-recycled subscriptions for the current school, including active and pending subscriptions.
GET/api/Webhooks/Subscriptions/{id}Get a subscription by ID, including recycled subscriptions.
POST/api/Webhooks/SubscriptionsCreate a subscription. Can enqueue a verification challenge immediately.
PATCH/api/Webhooks/Subscriptions/{id}Update the URL, description, signature mode, or subscribed event types. Updating the URL triggers a new verification challenge.
DELETE/api/Webhooks/Subscriptions/{id}Recycle (soft-delete) a subscription.
PUT/api/Webhooks/Subscriptions/{id}/RestoreRestore a recycled subscription to Pending.
PUT/api/Webhooks/Subscriptions/{id}/VerificationMark a subscription as verified and set it to Active.
POST/api/Webhooks/Subscriptions/{id}/VerificationChallengeSend a new verification challenge to the subscription URL.
POST/api/Webhooks/Subscriptions/{id}/TestSend a synchronous test event with a three-second timeout and return the receiver's response details.


Events and Deliveries

The Events and Deliveries endpoints supports the view of event triggers for the authenticated school, along with delivery attempts and the ability to trigger a delivery attempt.

MethodRouteDescription
GET/api/Webhooks/EventsList events. Supports eventTypeCode, dateFrom, and dateTo query parameters.
GET/api/Webhooks/Events/{eventId}Get an event by ID.
GET/api/Webhooks/Events/{eventId}/DeliveriesList all delivery attempts for an event.
POST/api/Webhooks/Events/{eventId}/ReplayRe-enqueue the event for each associated active subscription.


Event types

MethodRouteDescription
GET/api/Webhooks/EventTypesReturn the supported event-type catalog as a hierarchy of codes, descriptions, levels, and children.

Event codes are hierarchical. For example, subscribing to a code returned by the catalog associates that event type with the subscription. Query the catalog instead of hard-coding its contents because supported event types can change.


Certificates

The Certificate endpoints support the retrieval of the signing certificates required for validation of Webhook delivered content.

MethodRouteDescription
POST/api/Webhooks/CertificatesFetch current, non-recycled, non-expired public certificate PEMs for a JSON array of fingerprints. Unknown fingerprints are omitted.
GET/api/Webhooks/Certificates/{fingerprint}Fetch one public certificate PEM. This lookup can return a recycled or expired certificate.


Creating a subscription


POST /api/Webhooks/Subscriptions accepts:


PropertyTypeDescription
urlstringThe HTTPS endpoint that receives webhook requests.
descriptionstringA human-readable description of the receiver.
signatureModeinteger0 puts signature and webhook metadata in the body; 1 puts them in headers. Defaults to 0.
eventTypeCodesstring arrayEvent codes from GET /api/Webhooks/EventTypes. An empty array subscribes to no event types.
requireValidationbooleanWhen true, enqueue a verification challenge immediately after creation.


A successful request returns 201 Created, includes a Location header for the new resource, and returns the created subscription in the response body.


Quick start: register and verify an endpoint

The following example requires curl and jq. Set the API URL, an access token for a user with webhook write access, and the URL of your webhook receiver:

Bash

export API_BASE="https://services.timetabling.education"
export ACCESS_TOKEN="<access-token>"
export WEBHOOK_URL="https://receiver.example.com/webhooks/tds"

First, inspect the event catalog and select the event codes your receiver needs:

Bash

curl --fail --silent --show-error \
  --oauth2-bearer "$ACCESS_TOKEN" \
  "$API_BASE/api/Webhooks/EventTypes" | jq

Create a subscription. This example uses the Test event and skips the delivery validation challenge so creation can be checked independently:

Bash

subscription="$(
  curl --fail --silent --show-error \
    -X POST \
    --oauth2-bearer "$ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    --data "{
      \"url\": \"$WEBHOOK_URL\",
      \"description\": \"Webhook quick-start receiver\",
      \"signatureMode\": 1,
      \"eventTypeCodes\": [\"Test\"],
      \"requireValidation\": false
    }" \
    "$API_BASE/api/Webhooks/Subscriptions"
)"

subscription_id="$(printf '%s' "$subscription" | jq -er '.id')"
printf 'Created subscription %s\n' "$subscription_id"
printf '%s\n' "$subscription" | jq

Fetch the new subscription by ID and assert that its URL and event selection match the request:

Bash

created="$(
  curl --fail --silent --show-error \
    --oauth2-bearer "$ACCESS_TOKEN" \
    "$API_BASE/api/Webhooks/Subscriptions/$subscription_id"
)"

printf '%s\n' "$created" | jq
printf '%s\n' "$created" | jq -e \
  --arg expected_url "$WEBHOOK_URL" \
  '.id > 0
   and .url == $expected_url
   and (.eventTypeCodes | index("Test") != null)'

jq exits with status 0 when all checks pass and a non-zero status when the created record does not match.

To test the receiver as well as the stored configuration, send a test event:

Bash

curl --fail --silent --show-error \
  -X POST \
  --oauth2-bearer "$ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"message":"Webhook quick-start test"}' \
  "$API_BASE/api/Webhooks/Subscriptions/$subscription_id/Test" | jq

The test endpoint returns the delivery result, including the response received from the subscription URL. Use it to confirm that the receiver is reachable and returns the expected successful HTTP response.

Validation workflow

For receivers that implement the verification challenge:

  1. Create the subscription with requireValidation: true, or call POST /api/Webhooks/Subscriptions/{id}/VerificationChallenge later.
  2. Process the challenge at the subscription URL.
  3. Call PUT /api/Webhooks/Subscriptions/{id}/Verification to mark the subscription as verified and active.
  4. Fetch GET /api/Webhooks/Subscriptions/{id} and confirm that status is Active and verifiedOn has a value.

Updating a subscription

Send only the properties that should change. The PATCH body is the update object itself, not an instance wrapper:

Bash

curl --fail --silent --show-error \
  -X PATCH \
  --oauth2-bearer "$ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "description": "Updated receiver",
    "eventTypeCodes": ["Test", "Export"]
  }' \
  "$API_BASE/api/Webhooks/Subscriptions/$subscription_id" | jq

Inspecting events and deliveries

List recent events, optionally filtering by event type or ISO 8601 dates:

Bash

curl --fail --silent --show-error \
  --oauth2-bearer "$ACCESS_TOKEN" \
  "$API_BASE/api/Webhooks/Events?eventTypeCode=Test&dateFrom=2026-09-01T00:00:00Z" |
  jq

After selecting an event ID, inspect all attempts made to deliver it:

Bash

export EVENT_ID="<event-id>"

curl --fail --silent --show-error \
  --oauth2-bearer "$ACCESS_TOKEN" \
  "$API_BASE/api/Webhooks/Events/$EVENT_ID/Deliveries" | jq

Each delivery includes its subscription ID, attempt number, status, attempted time, HTTP status code, response body, and delivery key.

Exports

The first part of the system that will support Webhooks is the exports system. Currently the API supports the synchronous creation of exports, this will be discontinued at the end of 2026 in favour of an asynchronous process supported by Webhooks.


In order to subscribe a Webhook for exports do the following:

Bash

export API_BASE="https://services.timetabling.education"
export ACCESS_TOKEN="<access-token>"
export WEBHOOK_URL="https://receiver.example.com/webhooks/tds"

curl --fail --silent --show-error \
    -X POST \
    --oauth2-bearer "$ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    --data "{
      \"url\": \"$WEBHOOK_URL\",
      \"description\": \"Webhook quick-start receiver\",
      \"signatureMode\": 1,
      \"eventTypeCodes\": [\"Export.DOF.V9\"],
      \"requireValidation\": false
    }" \
    "$API_BASE/api/Webhooks/Subscriptions"

This will create a new subscription for Exports which will deliver the exported data to the endpoint "https://receiver.example.com/webhooks/tds".


Next queue an export of that type:

Bash

export API_BASE="https://services.timetabling.education"
export ACCESS_TOKEN="<access-token>"

curl --fail --silent --show-error \
    -X POST \
    --oauth2-bearer "$ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    --data "{
      \"type\": \"DOF\",
      \"subType\": \"V9\",
      \"fileId\": 1,
      \"date\": \"2026-07-12T0:00:00.000Z\"
    }" \
    "$API_BASE/api/SystemIO/Files/QueuedExports"

Now when the export completes receive the exported data at the registered endpoint and process it.


Further Reading

For additional documentation please see our under-development API documentation at https://services.dev.timetabling.education