SCORM Webhooks: Event-Driven Tracking for Learning Content

Webhooks send signed, queued deliveries to your systems when tracked events are recorded. Use them to synchronize learning progress, trigger follow-up workflows, and reconcile records with the session API.

Supported Event Types

These are the delivery and session event families supported by the platform:

Session events describe recorded completion, failure, or suspension transitions. Scores are included in session data when available; there is no separate score-change subscription. Course completion alone does not establish skill mastery.

Setting Up Webhooks

Step 1: Register Your Endpoint

Create an HTTPS endpoint that accepts POST requests. Register it under Dashboard → Integrations → Webhooks, or send the API request below. Replace the placeholders with your API key and a newly generated random signing secret. Store both server-side; use at least 16 characters for the signing secret and keep it separate from your API key.

curl -X POST https://app.allureconnect.com/api/v1/webhooks \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Completion handler",
  "url": "https://yourapp.com/webhooks/allureconnect",
  "eventScope": "sessions",
  "mode": "live",
  "signingSecret": "REPLACE_WITH_A_RANDOM_SERVER_SIDE_SECRET"
}'

Step 2: Select Scope and Mode

eventScope: "sessions" subscribes to the session event family. Use all for all supported event families, or select a family from the table. The registration API does not accept an individual-event list or package-ID filter; filter the signed payload in your receiver. The example uses LIVE mode. Use TEST mode with TEST content and credentials for isolated acceptance; an endpoint only receives events in its matching mode.

Step 3: Verify a Controlled Delivery

In your isolated test environment, register a TEST endpoint and complete a test session. Check delivery status, signature verification, duplicate handling, and the resulting progress record in your own system. A successful endpoint registration alone does not prove that this full workflow works.

Step 4: Verify and Persist Events

Read the X-Connect-Signature header, formatted as sha256=<hex digest>. Verify HMAC-SHA256 over the exact raw request body before parsing or acting on the payload. Do not verify a parsed and reserialized JSON object.

const crypto = require('node:crypto');

function verifyWebhookSignature(rawBody, signatureHeader, secret) {
  // Read X-Connect-Signature. Keep rawBody as the original Buffer or string.
  if (typeof secret !== 'string' || secret.trim().length === 0) return false;
  if (typeof signatureHeader !== 'string') return false;
  const match = /^sha256=([0-9a-f]{64})$/i.exec(signatureHeader.trim());
  if (!match) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
  return crypto.timingSafeEqual(Buffer.from(match[1], 'hex'), expected);
}

This synthetic example illustrates the session delivery envelope. Session fields are enriched from the available session record when queued; handle missing enrichment and reconcile current state through the session API.

{
  "event": "session.completed",
  "tenant_id": "tenant_example",
  "data": {
    "audit_event_id": "audit_example",
    "event_plane": "learner",
    "entity_type": "session",
    "entity_id": "sess_example",
    "severity": "info",
    "session_id": "sess_example",
    "package_id": "pkg_example",
    "learner_id": "learner_example",
    "completion_status": "completed",
    "success_status": "passed",
    "progress_percent": 100,
    "score": {
      "scaled": 0.92,
      "raw": 92,
      "min": 0,
      "max": 100
    },
    "session_time": "PT12M34S",
    "time_spent_seconds": 754,
    "updated_at": "2026-04-10T14:32:00.000Z"
  },
  "timestamp": "2026-04-10T14:32:00.000Z",
  "delivery_id": "whd_evt_audit_example_endpoint_example"
}

After verifying the signature, validate the expected tenant and event, then durably store or enqueue the delivery before returning a 2xx response. Process slower downstream work asynchronously. The delivery request has a 30-second timeout. Retryable failures can be retried; terminal HTTP or configuration failures enter the dead-letter queue immediately.

Retry Behavior and Dead-Letter Queue

For retryable failures, retries normally become eligible after 1 minute, 5 minutes, 15 minutes, and 1 hour respectively. A supported Retry-After response can change the next retry time, and queue scheduling can add delay. Retryable failures have a maximum of five attempts in total; terminal HTTP or configuration failures enter the dead-letter queue immediately. Review the failure, repair your receiver, and replay the delivery from the dashboard with a fresh attempt budget.

Common Use Cases

• Synchronize progress. Map signed session and learner identifiers to records in your LMS or CRM.
• Issue certificates. Check the recorded completion and success state against your certificate rules before issuing an award.
• Build reporting pipelines. Persist session events in your warehouse and reconcile them against API reads.
• Track delivery changes. Use dispatch lifecycle events to keep your distribution records current.

Best Practices

• Verify before processing. Reject missing or invalid signatures and unexpected tenants.
• Acknowledge durable receipt. Return 2xx only after your receiver has safely accepted the delivery.
• Handle duplicates. Persist the signed delivery_id with a uniqueness constraint. Retries and replays can repeat a delivery.
• Reconcile state. Do not let a delayed event overwrite newer progress. Re-read the session when ordering or state is uncertain.
• Monitor failed deliveries. Review the dead-letter queue and reconcile downstream records after recovery.

Read the webhook event reference for integration details.