# 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](https://docs.learnhouse.app/guides/custom-features/webhooks):

* 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.

| 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_version_restored`, `course_contributor_added`, `course_contributor_removed`, `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_resources_added` |
| Subscriptions | `pack_activated`, `pack_deactivated` |
| Organisation | `org_signup_method_changed`, `org_ai_config_changed`, `org_payments_config_changed` |

The envelope, from LearnHouse's documentation:

```json
{
  "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:

```bash
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`:

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/orgs/{org_id}/webhooks/events` | 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_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-secret` | Rotate the secret |
| `POST` | `/orgs/{org_id}/webhooks/{webhook_uuid}/test` | Send a `ping` event |
| `GET` | `/orgs/{org_id}/webhooks/{webhook_uuid}/deliveries` | 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](/docs/cli), then call the `test` operation to send a `ping`:

```bash
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](https://docs.learnhouse.app/guides/custom-features/webhooks#the-payload) has Next.js and Express examples.

### Node.js verification

```javascript
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:

```javascript
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](/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_id`s, and the [webhook idempotency guide](/webhooks/guides/implement-webhook-idempotency) 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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

### 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](https://hookdeck.com) gives each LearnHouse event the durability that three quick attempts can't.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle LearnHouse webhooks reliably in minutes.