Built LMS Help Center

Webhooks

Subscribe external systems to Built LMS event notifications.

Use webhooks when another system needs to react after Built LMS events happen. Use the REST API when the external system needs to request data on demand.

Before you begin

You need:

  • An API key with admin:api permission.
  • An HTTPS endpoint that accepts POST requests.
  • A receiver that can respond within 30 seconds.
  • A secure place to store the webhook secret.
  • A list of event types the integration needs.

Built LMS validates the endpoint when a webhook is created. The endpoint should return a 2xx response to validation requests.

Discover event types

Fetch the event catalog before creating subscriptions.

curl "https://{your-built-lms-domain}/api/public/v1/webhooks/event-types" \
  -H "Authorization: Bearer YOUR_API_KEY"

The catalog returns event names, descriptions, and JSON Schema payload definitions. Common event families include users, enrollments, certificates, exams, courses, learning paths, AI generation, survey responses, and mastery health threshold breaches.

Create a webhook

curl "https://{your-built-lms-domain}/api/public/v1/webhooks" \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/built-lms/webhooks",
    "events": ["enrollment.completed", "certificate.issued"]
  }'

Each webhook can subscribe to up to 10 event types. Each organization can have up to 20 webhook subscriptions.

The create response includes the webhook secret once. Store it immediately.

Verify signatures

Deliveries include an HMAC-SHA256 signature in the X-Webhook-Signature header.

X-Webhook-Signature: sha256=<hex_digest>

Verify the signature against the raw request body before trusting the payload.

import crypto from 'crypto';

function verifyBuiltLmsSignature(body: string, secret: string, header: string) {
  const expected = `sha256=${crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')}`;

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Handle the event envelope

Webhook deliveries use an envelope with event metadata and event-specific data.

{
  "event_id": "00000000-0000-0000-0000-000000000000",
  "event_type": "enrollment.completed",
  "timestamp": "2026-07-07T00:00:00.000Z",
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "api_version": "v1",
  "data": {}
}

Use event_id for idempotency so retries do not create duplicate work.

Manage deliveries

TaskEndpoint
List webhooksGET /api/public/v1/webhooks
Get one webhookGET /api/public/v1/webhooks/{id}
Update a webhookPUT /api/public/v1/webhooks/{id}
Disable or delete a webhookDELETE /api/public/v1/webhooks/{id}
Rotate a secretPOST /api/public/v1/webhooks/{id}/rotate-secret
Send a test deliveryPOST /api/public/v1/webhooks/{id}/test
Review delivery historyGET /api/public/v1/webhooks/{id}/deliveries
Retry a failed deliveryPOST /api/public/v1/webhook-deliveries/{id}/retry

Troubleshooting

On this page