Item Completions Incoming Webhook

The Item Completions Incoming Webhook lets external learning platforms report completions back to Learn Amp. When a user finishes content hosted outside Learn Amp - such as a security training course or a third-party e-learning platform - the external system sends a POST request, and Learn Amp automatically records the completion on the user's profile.

You can create multiple webhooks per company, each with its own name, credentials, field mapping, and source type filter. This makes it straightforward to connect several external systems simultaneously, or to isolate completions from different content providers.

Overview

The Item Completions Incoming Webhook is an HTTP endpoint that accepts completion notifications from external systems - so anything that can make a POST request can talk to it. Use it whenever you host learning content outside Learn Amp and still want that learning activity to appear on a user's profile, contribute to channel or pathway progress, or be visible in reporting.

Common use cases include:

Security awareness platforms (e.g. KnowBe4) sending phishing simulation or training completions
LinkedIn Learning, Go1, or other content libraries where the user views content in an external player
Bespoke internal tools or LMSs that need to push completion events into Learn Amp

Each webhook you create receives its own URL endpoint, its own secret key, and its own configuration. Different external systems can use different credentials and different field mappings, all feeding completions into the same Learn Amp company.

Functionality Breakdown

Webhook URL and Webhook Key

Every webhook has two credentials you share with the external system:

Webhook URL - the HTTPS endpoint the external system POSTs to:
https://YOUR-SUBDOMAIN.learnamp.com/webhooks/item_completions
Webhook Key - a UUID generated automatically when you create the webhook, used to authenticate each request

The key is sent by the external system as either an Authorization header or a key query parameter on each request. Learn Amp validates this key before processing any payload.

You can rotate a webhook key at any time using the Regenerate key button. The table on the Configure tab shows when each key was last rotated.

Field Mapping

Different external systems send completion data in different formats. Field mapping lets you tell Learn Amp how to translate an incoming payload into the fields it understands, without requiring changes to the external system.

You provide a JSON configuration per webhook that maps Learn Amp's field names to paths in the external payload. Dot notation lets you reach into nested objects - for example, user.email extracts the email address from a payload shaped like {"user": {"email": "..."}}.

Mappable fields are: email, item_id, source_id, slug, result, total_time, and score.

Identifying Items

When Learn Amp receives a completion, it needs to match the payload to a specific item in your library. It checks three possible identifiers in order of priority:

item_id - the Learn Amp internal ID (fastest and most precise)
source_id - an external identifier set on the item, optionally filtered by source type
slug - the URL slug of the item

Learn Amp uses the first identifier it finds a match for.

Source Type Filter

Each webhook can optionally restrict source_id lookups to items from a specific content source - for example, KnowBe4 or LinkedIn Learning. This is useful when multiple providers use overlapping external IDs, since it prevents a source_id from matching an item belonging to the wrong provider.

Identifying Users

Users are matched by their email address. Only active users are matched - deactivated or suspended accounts are not found, and the request returns a 404 Not Found.

Completion Recording

Once Learn Amp identifies both the user and the item, it records a completion. The payload can optionally include:

result - a pass/fail result string (e.g. "PASS", "FAIL")
score - a numeric score (e.g. 95 for 95%)
total_time - time spent in seconds (e.g. 120 for 2 minutes)

💡 Items must have Completion controlled externally enabled before they will accept webhook completions. If the item is found but this setting is not enabled, Learn Amp returns a 422 Unprocessable Entity - the completion is not silently ignored.

Pre-requisites

Before using the Item Completions Incoming Webhook, make sure the following are in place.

Role Requirements

Only Owners and Admins can manage webhooks - Managers and Learners won't see this area.

Role	Access

Role	Access
Owner	Can create, configure, and delete webhooks; can regenerate keys
Admin	Can create, configure, and delete webhooks; can regenerate keys
Manager	No access
Learner	No access

You will also need:

The integration enabled for your company (reach out to your Learn Amp representative)
At least one item in your library with Completion controlled externally turned on
An external system capable of making authenticated HTTP POST requests

FAQs

Q: Can I connect more than one external system?
Absolutely - you can create multiple webhooks for the same company, each with its own name, credentials, field mapping, and source type filter. Each external system uses its own webhook so there is no risk of one system's configuration affecting another.

Q: Does the webhook support scores, results, and time data?
Yes. In addition to recording a completion, you can include a result (e.g. "PASS" or "FAIL"), a numeric score, and a total_time in seconds. Use field mapping if your external system uses different field names.

Q: What happens if the item is not set to externally controlled?
Learn Amp returns a 422 Unprocessable Entity response and the completion is not recorded. Edit the item in Learn Amp (Edit item > Details > Completion) and enable Completion controlled externally.

Q: What content types support externally controlled completion?
Web links, YouTube video links, Vimeo video links, and items with embedded video or audio.

Q: What happens if the user cannot be found?
Learn Amp returns a 404 Not Found response with a JSON body: {"error": "User not found"}. Only active users are matched - check that the email address is correct and the user's account is active.

Q: Is it safe to share the Webhook Key?
Keep it private and share it only with the external system that needs it. If you suspect the key has been compromised, use the Regenerate key button. Any system using the old key must be updated immediately.

Q: Does field mapping affect all webhooks?
No - field mapping is configured per webhook. Each webhook has its own independent mapping.