Gareth Wilson Gareth Wilson

Guide to LearnHouse Webhooks: Features and Best Practices

Published


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

FeatureDetails
Signaturehex HMAC-SHA256
Signature headerx-webhook-signature
BodyJSON
Event routingBody field event

From LearnHouse's webhooks guide:

  • Headers on each request: X-Webhook-Event, X-Webhook-Delivery, X-Webhook-Signature and User-Agent: LearnHouse-Webhooks/1.0.
  • Any 2xx succeeds. Otherwise there are up to 3 attempts, 1 second then 4 seconds apart.
  • Delivery is at least once, so the same delivery_id can 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_id}/webhooks/events returns every event's payload schema, so you don't have to hard-code them.

CategoryEvents
Systemping
Learning progresscourse_completed, course_enrolled, activity_completed, assignment_submitted, assignment_graded, certificate_claimed
User and accessuser_signed_up, user_email_verified, user_role_changed, user_invited_to_org, user_removed_from_org
Course lifecyclecourse_created, course_published, course_deleted, course_update_published
Content managementactivity_version_created, activity_version_restored, course_contributor_added, course_contributor_removed, collection_created, podcast_episode_created
Collaborationboard_created, board_member_added, playground_created
Communitydiscussion_posted, comment_created, discussion_pinned, discussion_locked, discussion_vote_cast
Groupsusergroup_created, usergroup_deleted, usergroup_users_added, usergroup_resources_added
Subscriptionspack_activated, pack_deactivated
Organisationorg_signup_method_changed, org_ai_config_changed, org_payments_config_changed

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_WEBHOOK_SECRET. Paste the whole secret, including the whsec_ prefix. LearnHouse uses it as a plain HMAC key.

The other endpoint operations, all under /api/v1:

MethodPathPurpose
GET/orgs/{org_id}/webhooks/eventsList every event type and payload schema
POST/orgs/{org_id}/webhooksCreate an endpoint
GET/orgs/{org_id}/webhooksList endpoints
PUT/orgs/{org_id}/webhooks/{webhook_uuid}Update URL, events, active state
DELETE/orgs/{org_id}/webhooks/{webhook_uuid}Delete an endpoint
POST/orgs/{org_id}/webhooks/{webhook_uuid}/regenerate-secretRotate the secret
POST/orgs/{org_id}/webhooks/{webhook_uuid}/testSend a ping event
GET/orgs/{org_id}/webhooks/{webhook_uuid}/deliveriesRecent 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 .../deliveries after 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-secret and 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.