Client integrations

An integration should be designed as an operational process, not just as a list of endpoints. The client must know the authoritative source of data and the error-handling process.

What integrations are good for

Without an integration, Knowspread and your other systems are two registers of the same company, and someone has to keep them in step by hand: creating people, moving them between groups, copying completions across. An integration moves that work onto the systems.

• A new colleague has an account on day one. An employee joins. The HR system records them and the integration creates them in Knowspread under a stable identifier. Nobody retypes the name and e-mail, and after a change of surname the record stays the same one.
• A change of department shows up in training by itself. An employee moves to a new position. The HR system changes their group, and because groups can change content assignments, they receive the new department’s training without anyone assigning it one item at a time.
• A completion is written into the register. An employee finishes a mandatory course. Your system learns of it through the content_assignment_completed webhook, or by querying the API, and marks the requirement fulfilled. The Friday export and the retyping into a spreadsheet go away.

The table below sorts these situations by which way the data flows. Whichever direction you choose, start by choosing the identifier: a stable one survives a change of name or e-mail.

Common integration scenarios

Scenario	Direction	Note
User provisioning	External system -> Knowspread	Requires a stable identifier.
Group updates	External system -> Knowspread	Groups can change content assignments.
Content or event import	External system -> Knowspread	Useful for catalogues and blended learning.
Completion reporting	Knowspread -> external system	Can be handled by API polling or webhooks.
Webhook notifications	Knowspread -> external system	Requires an available HTTPS endpoint.

Identifiers

Depending on the context, user synchronization can use:

• internal ID,
• e-mail,
• personal_id,
• external group or content ID.

For long-term synchronization, the best identifier is stable and does not change when the user’s name or e-mail changes.

Webhooks

Webhooks are outgoing notifications from Knowspread. The current model includes:

• content_assignment_created,
• content_assignment_completed,
• content_assignment_overdue,
• test_attempt_completed.

The client endpoint must use HTTPS. Supported authentication modes are no authentication, Basic Auth, and OAuth2 client credentials. If a secret is set, the client can verify the payload signature.