Guide to LearnHouse Webhooks: Features and Best Practices
LearnHouse is an open-source learning platform for building courses with activities, assignments and certificates, plus discussions, boards and user groups around them. Organisations run it on LearnHouse's cloud or self-host it. Its webhooks report what learners and admins do, such as an enrolment, a completed course or a graded assignment, so a CRM, email tool or reporting dashboard can follow along without polling the API.
This guide walks through creating a LearnHouse endpoint through the API, the 39 events and their envelope, checking X-Webhook-Signature, and why a retry schedule that lasts five seconds shapes your design.
What are LearnHouse webhooks?
Webhooks are a Pro feature, managed per organisation by an authenticated user, either in organisation settings or through the webhook API. Each endpoint is a public HTTPS URL with its own event list and its own whsec_ secret.
When a subscribed event fires, LearnHouse posts a JSON envelope, signs the body with the endpoint's secret, and logs the delivery so you can review it later. Before every delivery it also checks the target URL and the IP address it resolves to, and refuses localhost and private or reserved ranges in every environment, self-hosted included.
LearnHouse webhook features
| Feature | Details |
|---|---|
| Signature | hex HMAC-SHA256 |
| Signature header | x-webhook-signature |
| Body | JSON |
| Event routing | Body field event |
From LearnHouse's webhooks guide:
- Headers on each request:
X-Webhook-Event,X-Webhook-Delivery,X-Webhook-SignatureandUser-Agent: LearnHouse-Webhooks/1.0. - Any
2xxsucceeds. Otherwise there are up to 3 attempts, 1 second then 4 seconds apart. - Delivery is at least once, so the same
delivery_idcan arrive twice. - Secrets are stored encrypted and shown only at creation and rotation.
Events and payloads
The shape of data depends on the event. GET /api/v1/orgs/{org_ returns every event's payload schema, so you don't have to hard-code them.
| Category | Events |
|---|---|
| System | ping |
| Learning progress | course_completed, course_enrolled, activity_completed, assignment_submitted, assignment_graded, certificate_claimed |
| User and access | user_signed_up, user_email_verified, user_role_changed, user_invited_to_org, user_removed_from_org |
| Course lifecycle | course_created, course_published, course_deleted, course_update_published |
| Content management | activity_version_created, activity_, course_contributor_added, course_, collection_created, podcast_episode_created |
| Collaboration | board_created, board_member_added, playground_created |
| Community | discussion_posted, comment_created, discussion_pinned, discussion_locked, discussion_vote_cast |
| Groups | usergroup_created, usergroup_deleted, usergroup_users_added, usergroup_ |
| Subscriptions | pack_activated, pack_deactivated |
| Organisation | org_, org_ai_config_changed, org_ |
The envelope, from LearnHouse's documentation:
{
"event": "course_completed",
"delivery_id": "dlv_1a2b3c4d5e6f7081",
"timestamp": "2026-06-22T12:00:00Z",
"org_id": 1,
"data": {
"user": { "user_uuid": "user_…", "email": "learner@example.com", "username": "learner" },
"course": { "course_uuid": "course_…", "name": "Introduction to Python" }
}
}
event matches the X-Webhook-Event header and delivery_id matches X-Webhook-Delivery. org_id tells a shared receiver which organisation the event came from. The docs list event names by category but describe each one only through the schema endpoint, so fetch it before mapping fields for events beyond the common learning ones.
Setting up LearnHouse webhooks
Create an endpoint in organisation settings, or through the API with a user JWT:
curl -X POST "https://<your-learnhouse-host>/api/v1/orgs/<org_id>/webhooks" \
-H "Authorization: Bearer <user_jwt>" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.example.com/webhooks/learnhouse",
"events": ["course_completed", "course_enrolled", "user_signed_up"]
}'
The response includes secret, prefixed whsec_, exactly once. Store it as LEARNHOUSE_. Paste the whole secret, including the whsec_ prefix. LearnHouse uses it as a plain HMAC key.
The other endpoint operations, all under /api/v1:
| Method | Path | Purpose |
|---|---|---|
GET | /orgs/{org_ | List every event type and payload schema |
POST | /orgs/{org_id}/webhooks | Create an endpoint |
GET | /orgs/{org_id}/webhooks | List endpoints |
PUT | /orgs/{org_ | Update URL, events, active state |
DELETE | /orgs/{org_ | Delete an endpoint |
POST | /orgs/{org_ | Rotate the secret |
POST | /orgs/{org_ | Send a ping event |
GET | /orgs/{org_ | Recent delivery logs |
To route through Hookdeck, create a LearnHouse source, paste the full secret into its verification settings, and use the source URL as the endpoint url. Because LearnHouse rejects private addresses, a public tunnel is the only way to reach a laptop. Run the Hookdeck CLI, then call the test operation to send a ping:
npx hookdeck-cli listen 3000 learnhouse --path /webhooks/learnhouse
Securing LearnHouse webhooks
X-Webhook-Signature is sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with the full whsec_ secret. Strip the prefix, compute the HMAC over the bytes you received, and compare in constant time. The payload section has Next.js and Express examples.
Node.js verification
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['x-webhook-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const message = rawBody;
const candidates = [signature.startsWith('sha256=') ? signature.slice(7) : signature];
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
LearnHouse's retries are over within about 5 seconds, so the handler only stores the event and returns:
const express = require('express');
const app = express();
app.post('/webhooks/learnhouse', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.LEARNHOUSE_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
let envelope;
try {
envelope = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) return res.sendStatus(400);
try {
if (envelope.event === 'ping') return res.sendStatus(200);
await saveLearnHouseEvent(envelope.delivery_id, {
event: envelope.event,
orgId: envelope.org_id,
occurredAt: envelope.timestamp,
data: envelope.data,
});
} catch {
return res.sendStatus(503);
}
res.sendStatus(200);
});
saveLearnHouseEvent ignores a delivery_id it already has. A worker then sends the certificate email or updates the CRM.
No timestamp is signed, so the body's timestamp can't be used to reject old requests. Hookdeck's LearnHouse source checks the same sha256= HMAC, applies no time window, answers LearnHouse with 200, and records signature mismatches as failed verification.
Make LearnHouse webhooks production-ready. Hookdeck Event Gateway verifies each LearnHouse delivery and keeps retrying your CRM or email service long after LearnHouse's three quick attempts are used up.
LearnHouse webhook limitations and pain points
Three attempts in five seconds
The Problem: A deploy, restart or brief outage loses enrolments and completions.
Why It Happens: LearnHouse makes up to 3 attempts, waiting 1 second and then 4 seconds. Anything longer than a few seconds of downtime exhausts them.
Workarounds:
- Run more than one receiver instance and deploy without downtime.
- Check
GET .../deliveriesafter any incident and rebuild missed state from the LearnHouse API.
How Hookdeck Can Help: Hookdeck accepts the delivery on LearnHouse's first attempt and retries your service for as long as your policy says.
No private or local targets
The Problem: You can't point a webhook at an internal service or a development machine, even on a self-hosted LearnHouse.
Why It Happens: LearnHouse checks the URL and the resolved IP before every delivery and rejects localhost and private or reserved ranges in all environments.
Workarounds:
- Expose a public HTTPS receiver that forwards internally.
- Use a public tunnel for local development.
How Hookdeck Can Help: A Hookdeck source gives LearnHouse a public URL, and Hookdeck delivers to your destination or, through the CLI, to localhost.
Event schemas aren't in the docs
The Problem: You don't know what data contains for many of the 39 events until you call the API or receive one.
Why It Happens: The documentation lists event names by category and serves the schemas from GET .../webhooks/events.
Workarounds:
- Fetch the schema list and generate types from it.
- Subscribe a test endpoint to everything and capture real deliveries.
How Hookdeck Can Help: Hookdeck keeps the full body and headers of every delivery, so you can inspect real payloads for each event type.
The secret is shown once
The Problem: Losing the secret means rotating it.
Why It Happens: LearnHouse returns the secret only at creation and rotation.
Workarounds:
- Store it in a secret manager immediately.
- Rotate with
regenerate-secretand update your receiver straight away.
How Hookdeck Can Help: With a Hookdeck source in between, a rotated secret is updated on the source only.
Best practices
Key on delivery_id
LearnHouse tells you to record processed delivery_ids, and the webhook idempotency guide shows how to do it durably.
Return 2xx first
With only 5 seconds of retries, any slow work in the request path costs you events. Move it to a queue, as described in processing webhooks asynchronously.
Route on the event header
X-Webhook-Event names the event before you parse the body, which makes it easy to route at a proxy or gateway.
Subscribe to what you use
Start with the learning events your product needs, such as course_enrolled, course_completed and assignment_submitted, and add others later.
Conclusion
LearnHouse webhooks send learning, community and admin events in a consistent envelope, signed with an HMAC-SHA256 of the body in X-Webhook-Signature. Verify the raw bytes with the full whsec_ secret, store each event by delivery_id, and respond immediately, because LearnHouse retries for only a few seconds.
Hookdeck Event Gateway gives each LearnHouse event the durability that three quick attempts can't.
Get started with Hookdeck for free and handle LearnHouse webhooks reliably in minutes.