Agent skill

LearnHouse Webhooks Skill

Receive and verify LearnHouse webhooks. Use when setting up LearnHouse webhook handlers, debugging X-Webhook-Signature verification, or handling events such as course_completed, course_enrolled, assignment_submitted and user_signed_up.

Install this skill

npx skills add hookdeck/webhook-skills --skill learnhouse-webhooks


When to Use This Skill

  • How do I receive LearnHouse webhooks?
  • How do I verify the LearnHouse X-Webhook-Signature header?
  • How do I handle course_completed, course_enrolled or assignment_graded events?
  • Why is my LearnHouse webhook signature verification failing?
  • How do I deduplicate LearnHouse deliveries on delivery_id?

How LearnHouse Signs Webhooks

LearnHouse (open-source learning platform, cloud or self-hosted) POSTs a JSON envelope to your endpoint. Webhooks are a Pro feature.

  • Header: X-Webhook-Signature: sha256=<hex>
  • Algorithm: HMAC-SHA256, lowercase hex
  • Signed content: the raw request body bytes only. No timestamp, id or other header is signed, so there is no replay window to check.
  • Key: the endpoint secret (whsec_...), used whole, prefix included, as plain UTF-8 bytes. This is not Standard Webhooks: do not strip whsec_, do not base64-decode it, and do not use the standardwebhooks or svix libraries.
  • Missing, malformed or mismatched signature: respond 401.

Verification (core)

const crypto = require('crypto');

function verifyLearnhouseSignature(rawBody, header, secret) {
  if (!header || !secret) return false;
  const value = header.startsWith('sha256=') ? header.slice(7) : header; // bare digest also accepted
  if (!/^[0-9a-fA-F]{64}$/.test(value)) return false; // validate before decoding
  const expected = crypto.createHmac('sha256', Buffer.from(secret, 'utf8')).update(rawBody).digest();
  return crypto.timingSafeEqual(Buffer.from(value, 'hex'), expected);
}
import hmac, hashlib, re

def verify_learnhouse_signature(raw_body: bytes, header: str | None, secret: str | None) -> bool:
    if not header or not secret:
        return False
    value = header[len("sha256="):] if header.startswith("sha256=") else header
    if not re.fullmatch(r"[0-9a-fA-F]{64}", value):
        return False
    expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).digest()
    return hmac.compare_digest(bytes.fromhex(value), expected)

raw_body / rawBody must be the exact bytes received: never decode and re-encode, and never JSON.parse/JSON.stringify before verifying. Hex is compared case-insensitively.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Handling Events

Dispatch on the body's event field (the same name is also sent in the X-Webhook-Event header). Treat every field of the parsed body as untrusted and check its type before reading into it. Deliveries are at-least-once: dedupe on delivery_id (also sent as X-Webhook-Delivery).

{
  "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" }
  }
}

Common Event Types

LearnHouse documents 39 event types; the full list is in references/overview.md.

EventTriggered When
pingYou send a test from the dashboard or POST .../test
course_enrolledA learner enrolls in a course
course_completedA learner completes a course
activity_completedA learner completes an activity
assignment_submittedA learner submits an assignment
assignment_gradedAn assignment is graded
certificate_claimedA learner claims a certificate
user_signed_upA user signs up to the organization

Environment Variables

LEARNHOUSE_WEBHOOK_SECRET=whsec_your_endpoint_secret

Paste the whole secret, including the whsec_ prefix. LearnHouse uses it as a plain HMAC key.

Local Development

LearnHouse rejects localhost and private IPs, so a local receiver needs a public tunnel. Run the Hookdeck CLI via npx (no install, no account required):

npx hookdeck-cli listen 3000 learnhouse --path /webhooks/learnhouse

Use the tunnel URL as the endpoint URL in LearnHouse. If you route deliveries through Hookdeck, its LearnHouse source verifies the signature (set the source secret to the full whsec_... value).

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →