Skip to content
Honen Academy

Docs

Webhooks

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

  1. Open Organization → Developers → Webhooks.
  2. Add an endpoint and enter its URL. The URL must start with https:// and be reachable from the internet.
  3. Choose the events to receive.
  4. 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.
  5. 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 webhooks section.
  • 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.

Webhooks | Honen Academy