Credentials Webhook

When a school administrator activates your platform application, the Untis Platform sends a credentials transfer webhook to your configured endpoint. This webhook delivers everything your application needs to authenticate against the Untis Platform APIs on behalf of that school.

Credential transfer via webhook is the recommended approach. The alternative — manual entry by the school administrator — is error-prone and does not scale.

When this webhook is sent

eventType	Trigger
CREATED	A school administrator activates your application for the first time
REACTIVATED	An application that was previously deactivated is re-activated by the school
RESET	A password reset was triggered on the platform — new credentials are issued

Endpoint requirements

Your credentials webhook endpoint must:

• Be reachable via HTTPS
• Accept POST requests with Content-Type: application/json
• Return a 2xx response to acknowledge receipt
• Verify the request signature before processing — see Step 1 in Handling requirements below

The endpoint URL is configured in PAM when your platform application is set up.

Payload

The payload is a JSON object containing credentials and metadata for the activated tenant (Credentials API specification v2).

Field	Type	Description
tenantId	string	Unique identifier for the school/tenant
clientId	string	The OIDC client ID. Used as the client_id parameter in auth requests and as the Basic Auth username for Client Credentials token requests
secret	string	The OIDC client secret. Used as client_secret in the Authorization Code token exchange
password	string	The platform-generated password. Used as the Basic Auth password for Client Credentials token requests (not the OIDC secret)
host	string	The Untis Platform host for this school (e.g. localhost, or the school’s assigned subdomain)
country	string	Country of the school (e.g. AT, DE)
region	string	Region/state of the school (e.g. AT-3)
language	string	Primary language of the school (e.g. de)
eventType	string	The reason for this delivery: CREATED, REACTIVATED, or RESET
activatorEmail	string	Email address of the school administrator who activated the application
activatorUsername	string	Username of the school administrator who activated the application
schoolEmail	string	Contact email address of the school
schoolPhoneNumber	string	Contact phone number of the school

Attribute order and signature verification

The signature is computed over the raw JSON body bytes. The fields must be read and verified in the order they arrive — do not re-serialise the payload before verifying.

Example payload:

v2 (Current)

{
  "tenantId": "12345",
  "clientId": "BestApp-tenant-12345",
  "secret": "test-secret",
  "password": "test-password",
  "host": "localhost",
  "country": "AT",
  "region": "AT-3",
  "language": "de",
  "eventType": "CREATED",
  "activatorEmail": "jane@doe.com",
  "activatorUsername": "Jane Doe",
  "schoolEmail": "school@entenhausen.com",
  "schoolPhoneNumber": "555 / 123 456 789"
}

v1 (Deprecated)

Migrate to v2

v1 included a schoolName field and did not include eventType, activatorEmail, activatorUsername, schoolEmail, or schoolPhoneNumber. schoolName has been removed and is no longer delivered.

{
  "tenantId": "12345",
  "clientId": "BestApp-tenant-12345",
  "secret": "test-secret",
  "password": "test-password",
  "host": "localhost",
  "country": "AT",
  "region": "AT-3",
  "language": "de",
  "schoolName": "Example School"
}

Handling requirements

1. Verify the signature first — before reading any field. See Verifying the Untis Platform Identity.

2. Store credentials per tenant — use tenantId as the key. Never share credentials across tenants. Every school activation delivers a separate set of credentials.

3. Store securely — use a secrets manager or encrypted storage. Never log or store credentials in plain text.

4. Overwrite on redelivery — for REACTIVATED and RESET events, overwrite the stored credentials for the matching tenantId with the newly delivered values. The previous credentials are no longer valid.

5. Respond 2xx promptly — acknowledge receipt quickly. Perform storage asynchronously if necessary to avoid timeout retries from the platform.

6. Use metadata for routing — country, region, and language are informational. Use them for routing requests to regional infrastructure or for localisation if your application requires it.

What to do if the webhook is not received

If your endpoint was temporarily unavailable, the school administrator can re-trigger delivery or manually copy the credentials into your application’s UI. Build a manual credential entry fallback for resilience, even if webhook delivery is your primary path.

Relevant articles

Verifying the Untis Platform Identity How to verify the request signature.

Deactivation Webhook Handling when a school deactivates.

Authentication Model Conceptual overview of platform credentials.

Get Your Platform Application Configure your webhook endpoint.