A webhook tells your system the moment something happens in Honen, such as a learner completing a course. Honen sends a signed request to a URL you choose, so you do not need to keep checking the API.
Webhooks are available in organization workspaces. You need the Manage integrations permission.
Add an endpoint
- Open Organization → Developers → Webhooks.
- Add an endpoint and enter its URL. The URL must start with
https://and be reachable from the internet. - Choose the events to receive.
- Save, then copy the signing secret. It starts with
whsec_and is shown only once. If you lose it, rotate the secret to get a new one. - Send a test delivery to confirm your endpoint responds.
Events for learning and enrollment
| Event | Sent when |
|---|---|
course.started |
A learner first opens or works on a course |
course.progress.updated |
A learner's progress in a course changes |
course.completed |
A learner completes a course |
assignment.assigned |
An assignment reaches a learner |
assignment.completed |
A learner completes an assignment |
enrollment.access_granted |
A person or group is given access to a course, or a course is added to a group |
enrollment.access_removed |
That access is removed |
The course. and assignment. events are sent however the learner got there. For example, assignment.assigned is also sent when someone joins a group that already has an assignment.
The enrollment. events are sent when access is changed in a course's access settings and when a course is added to or removed from a group. They are not sent for access that comes from a shared course link, a curriculum, a catalog, or a Site.
To see everything a person has been assigned, read POST /api/v1/learning/progress.
More events cover activities, tests, projects, catalogs, publishing reviews, workspace members, and groups. The endpoint editor lists all of them.
course.progress.updated can be sent often and does not include the percentage. When you receive it, read the current numbers with POST /api/v1/learning/progress, sending the userId and courseId from the event.
What Honen sends
Each delivery is a POST with a JSON body:
{
"id": "6740f0c1a2b3c4d5e6f70812",
"type": "course.completed",
"version": 1,
"occurredAt": "2026-01-01T00:00:00.000Z",
"workspaceId": "66f0a1b2c3d4e5f607182930",
"actor": { "id": "66f1a2b3c4d5e6f708192a3b" },
"resource": { "type": "course", "id": "66f2a3b4c5d6e7f8091a2b3c" },
"data": {
"workspaceId": "66f0a1b2c3d4e5f607182930",
"userId": "66f1a2b3c4d5e6f708192a3b",
"courseId": "66f2a3b4c5d6e7f8091a2b3c",
"courseName": "Safety basics",
"grade": 92,
"completedAt": "2026-01-01T00:00:00.000Z",
"catalogId": null,
"catalogEntryId": null,
"releaseId": null
}
}
userId is the person's Honen ID. To match it to your own records, call POST /api/v1/members/get with that userId and read member.user.email or member.externalIds. See Use the API and OpenAPI reference.
Check the signature
Every delivery includes these headers:
| Header | Value |
|---|---|
X-Honen-Webhook-Id |
The event ID. It stays the same when a delivery is retried |
X-Honen-Webhook-Event |
The event type |
X-Honen-Webhook-Timestamp |
When the request was signed, in Unix seconds |
X-Honen-Webhook-Signature |
v1= followed by the signature |
X-Honen-Webhook-Attempt |
The attempt number, starting at 1 |
To check a delivery, compute an HMAC-SHA256 of the timestamp, a period, and the exact request body, using your signing secret. Compare the result, in hex, with the value after v1=. Reject requests whose signature does not match or whose timestamp is more than a few minutes old.
Retries
Respond with any 2xx status within 10 seconds. Do slow work after you respond.
If your endpoint does not respond in time or returns another status, Honen tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. After six attempts the delivery is marked failed. You can retry a failed delivery from the endpoint's delivery log.
A delivery can arrive more than once, and deliveries can arrive out of order. Use X-Honen-Webhook-Id to ignore repeats.
Webhooks are for speed. Treat the API as the record: catch up after downtime, and on a regular schedule, with POST /api/v1/learning/progress.
Find the events in the API reference
Every event is also described in Honen's OpenAPI document, with its payload fields and an example.
- In an API reference built from that document, events are listed under Webhooks, next to the endpoints. Each one is marked EVENT.
- OpenAPI 3.1 lists them in the standard
webhookssection. - OpenAPI 3.0 lists them under
x-webhooks, because OpenAPI 3.0 has no webhooks section.
A few events, such as the catalog and publishing review events, do not have their fields listed yet. Look at a delivery in the endpoint's delivery log to see the exact payload.
