Statements Resource

Description

The Statements endpoint is a lightweight LRS (Learning Record Store) interface that accepts xAPI-style learning activity records from Articulate Rise 360 modules or similar eLearning tools. Each statement is uniquely identified and captures learner activity, including actor, verb, object, result, and context information.

This endpoint supports receiving PUT operations from training modules and immediately forwards the received statement to the corresponding organization's webhook.

Statements

Each statement represents a single recorded learning interaction tied to a user, a learning object, and an action (e.g., “attempted”, “completed”).

---

Webhook Forwarding Behavior

When a statement is received:

1. The system validates the session token, identifying the learner and associated organization.

2. The organization’s webhook URL is retrieved from the organization document.

3. The entire validated statement is forwarded via POST to the organization's webhook in the following format:

Example Forwarded Payload:

{
  "statementId": "7a64e0f2-1a38-4de6-9f39-142d7e9996cb",
  "organizationId": "org123",
  "receivedAt": "2025-07-25T14:49:00.000Z",
  "statement": {
    "id": "7a64e0f2-1a38-4de6-9f39-142d7e9996cb",
    "timestamp": "2025-07-25T14:48:00.000Z",
    "actor": {
      "objectType": "Agent",
      "name": "Jane Doe",
      "mbox": "mailto:[e-mail]"
    },
    "verb": {
      "id": "https://adlnet.gov/expapi/verbs/attempted",
      "display": {
        "en-US": "attempted"
      }
    },
    "result": {
      "duration": "PT5M33S",
      "completion": true,
      "success": true
    },
    "context": {
      "registration": "d8b3a3e3-b34a-442f-8b17-dcb44f0f2fae"
    },
    "object": {
      "id": "https://training.example.com/modules/mod123",
      "objectType": "Activity",
      "definition": {
        "type": "http://adlnet.gov/expapi/activities/lesson"
      }
    }
  }
}

1. The request to the webhook is made using HTTPS POST.

2. No retries or queueing is done by default—this is a fire-and-forget delivery model unless otherwise configured.

If the webhook fails (e.g., 5xx status or timeout), the statement is still considered accepted. Future reliability features (like retry queues or dead-letter storage) may be added later.

---

Example

Statement (xAPI-like):

{
  "id": "7a64e0f2-1a38-4de6-9f39-142d7e9996cb",
  "timestamp": "2025-07-25T14:48:00.000Z",
  "actor": {
    "objectType": "Agent",
    "name": "Jane Doe",
    "mbox": "mailto:[e-mail]"
  },
  "verb": {
    "id": "https://adlnet.gov/expapi/verbs/attempted",
    "display": {
      "en-US": "attempted"
    }
  },
  "result": {
    "duration": "PT5M33S",
    "completion": true,
    "success": true
  },
  "context": {
    "registration": "d8b3a3e3-b34a-442f-8b17-dcb44f0f2fae"
  },
  "object": {
    "id": "https://training.example.com/modules/mod123",
    "objectType": "Activity",
    "definition": {
      "type": "http://adlnet.gov/expapi/activities/lesson"
    }
  }
}

---

Submit Statement – (Rise 360 Module)

PUT /statements

Headers:

Authorization: Bearer <Session token>
Content-Type: application/json

Query Parameters:

Name	Type	Required	Description
statementId	string	✅	A unique identifier for the statement
...custom	any	❌	Any other optional tracking params

Example Request:

PUT /statements?statementId=7a64e0f2-1a38-4de6-9f39-142d7e9996cb

{
  "id": "7a64e0f2-1a38-4de6-9f39-142d7e9996cb",
  "timestamp": "2025-07-25T14:48:00.000Z",
  "actor": {
    "objectType": "Agent",
    "name": "Jane Doe",
    "mbox": "mailto:[e-mail]"
  },
  "verb": {
    "id": "https://adlnet.gov/expapi/verbs/attempted",
    "display": {
      "en-US": "attempted"
    }
  },
  "result": {
    "duration": "PT5M33S",
    "completion": true,
    "success": true
  },
  "context": {
    "registration": "d8b3a3e3-b34a-442f-8b17-dcb44f0f2fae"
  },
  "object": {
    "id": "https://training.example.com/modules/mod123",
    "objectType": "Activity",
    "definition": {
      "type": "http://adlnet.gov/expapi/activities/lesson"
    }
  }
}

Example Response (200 OK):

{
  "success": true,
  "message": {
    "action": "handled",
    "resource": "statement",
    "success": true
  },
  "data": {
    "statement": {
      // The statement object sent in the request body
    },
    "organizationId": "example-organization-id", // The organization ID extracted from the session
    "message": "Webhook succeeded with status 200"
  },
  "metadata": null
}

---

Authentication

This endpoint requires a valid session token generated, validated, and signed by Training Arc.

• Header: Authorization: Bearer <Session token>

The session token identifies the user and maps them to their organization, allowing the server to retrieve the appropriate webhook destination.

---

Validations

• statementId optional but likely helpful for organization webhook.

• actor.mbox or actor.account optional but likely helpful for org webhook identifying learner.

• verb.id must be a valid IRI (e.g., xAPI verb URL).

• object.id must be a valid IRI and reference a known module if applicable.

• timestamp must be an ISO 8601-compliant date string.

• duration (if included) must follow ISO 8601 duration format (e.g., PT10M23S).

---

Error Responses

400 Bad Request If required fields are missing or formatted incorrectly.

{
  "success": false,
  "message": "Invalid xAPI statement format."
}

401 Unauthorized If the session token is missing or invalid.

{
  "success": false,
  "message": "Unauthorized"
}

403 Forbidden If the session token is signed but belongs to a different org or user.

{
  "success": false,
  "message": "Invalid token"
}