Sending webhooks to your systems
A webhook is Learnient calling you. When something happens — a user is created, a course is published — Learnient sends an HTTP request to an address you own, so your system finds out immediately instead of asking repeatedly.
The Learnient webhook reference lists every event with its exact payload, how to verify the signature on each request, and how retries work. This article covers setting webhooks up in Learnient; the reference is what your developers build against.
Where it is
Section titled “Where it is”Choose Admin, then Developer and Webhooks.
Creating one
Section titled “Creating one”- Choose New webhook.
- Give it a name that says which system it feeds.
- Enter the URL Learnient should call. It has to be reachable from the internet — a machine on your office network is not.
- Choose the events that should trigger it.
- Save.
What you can subscribe to
Section titled “What you can subscribe to”Events are grouped by what they are about:
| Group | Events |
|---|---|
| People | Created, updated, deactivated, reactivated, deleted |
| Your organisation | Departments, locations, job titles, skills, groups and course categories: created, updated, deleted |
| Courses | Created, updated, published, unpublished, archived, deleted |
| Enrolments | Enrolled, removed, deadline missed |
| Learning | Started, completed, passed, failed, certificate awarded, completion held for sign-off, sign-off rejected |
| Learning paths | Enrolled, unenrolled, completed |
| Practice | A practice session completed |
The exact event names and every field each one sends are in the webhook reference.
Webhook events for course completion and sign-off
Section titled “Webhook events for course completion and sign-off”Learning events tell you what happens on a learner’s course. Two cover the post-course process:
| Event | Fires when |
|---|---|
course.completion_held | A learner finished the content, and the course is waiting for a sign-off or attestation — useful for booking the observation |
course.signoff_rejected | A qualified person did not sign the learner off; the reason is included. The attempt closes as failed, so course.failed is sent too, with completion_release_source set to not_signed_off, and the learner takes the course again |
course.completed and course.passed fire when a course actually completes — for a held course, that is when it is signed off, not when the content was finished. Their payloads include completion_release_source, which says how it was completed: not_required, process_completed, requirement_withdrawn, imported_with_signoff or imported_without_signoff. On course.failed it can also be not_signed_off.
Subscribe to what you will act on. A webhook firing into a system that ignores it is a queue of deliveries nobody reads and a source of noise when one fails.
Deliveries, and what happens when one fails
Section titled “Deliveries, and what happens when one fails”Every send is recorded with the attempt number, the response code your endpoint returned, and whether it succeeded.
A failed delivery is retried rather than dropped, with a time recorded for the next attempt.
Two consequences worth designing for:
Your endpoint must answer quickly. Learnient is waiting on a response, so do the minimum — accept the payload, put it on your own queue, answer. Work done before answering is work done while a timeout runs.
Your endpoint must tolerate the same event arriving twice. A retry after a response that never arrived delivers an event you already processed. Each delivery carries an event identifier, so the safe pattern is to record what you have handled and ignore repeats.
Testing one
Section titled “Testing one”Point a new webhook at a service that echoes what it receives before pointing it at anything real. That tells you the shape of the payload and confirms the address is reachable, which are the two things that go wrong first.
Webhooks or the API?
Section titled “Webhooks or the API?”Use a webhook when you want to know the moment something happens and you own an address Learnient can reach. Use the Learnient Public API with an API key when your system needs to ask Learnient questions on its own schedule, or when nothing of yours is reachable from the internet.
Most integrations end up using both: webhooks to know something changed, the API to fetch the detail.
What happens when you save
Section titled “What happens when you save”The webhook starts firing on the next matching event. Nothing is sent for events that happened before you created it, so a webhook is not a way to backfill — that is what the API is for.