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:apipermission. - An HTTPS endpoint that accepts
POSTrequests. - 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
| Task | Endpoint |
|---|---|
| List webhooks | GET /api/public/v1/webhooks |
| Get one webhook | GET /api/public/v1/webhooks/{id} |
| Update a webhook | PUT /api/public/v1/webhooks/{id} |
| Disable or delete a webhook | DELETE /api/public/v1/webhooks/{id} |
| Rotate a secret | POST /api/public/v1/webhooks/{id}/rotate-secret |
| Send a test delivery | POST /api/public/v1/webhooks/{id}/test |
| Review delivery history | GET /api/public/v1/webhooks/{id}/deliveries |
| Retry a failed delivery | POST /api/public/v1/webhook-deliveries/{id}/retry |
Troubleshooting
Confirm the endpoint is HTTPS, accepts POST, and returns a 2xx response within
30 seconds.
Treat event_id as an idempotency key. Store processed event IDs before running
side effects.
Verify against the raw request body, not a parsed and reserialized JSON object. Also confirm the webhook secret was stored from the create or rotate response.
Fetch /api/public/v1/webhooks/event-types with the same API key. The catalog
is the source of truth for available subscription events.