Skip to content

learningBOX PUSH Notification Specification

When a learner earns a configured badge, learningBOX POSTs JSON data to the specified URL (available since learningBOX 2.9.0).

Overview

  • POSTs JSON data to the specified notification URL based on the notification type. Currently supports the "badge earned" event.

Use Cases

  • Use this feature to post information to your core system when a user performs a specified action (currently only on badge earn).

Communication Specification

  • Protocol: https
  • HTTP Method: POST
  • Content-Type: application/json
  • Endpoint: Your specified URL

Behavior and Retry

  • For LMS notification type, the response is checked and retried if unsuccessful.
  • Retries occur 3 times at 10-minute intervals. If all retries fail, a failure email is sent to the administrator according to your settings.

Expected Response from Receiver

  • On success: Return HTTP 200 OK with response body 1.
  • On failure: Any return value.

POSTed JSON Fields

  • scope: PUSH notification category (fixed value: "badge")
  • action: create | delete
  • sco_id: Internal ID of the learning content stored in our system's DB
  • sco_code: Learning content code
  • badge_code: Badge code
  • score: Grade score / achievement rate
  • user_id: Internal ID of the user stored in our system's DB
  • user_login: User's login ID
  • user_email: User's registered email address
  • datetime: Date and time
  • hash: Hash value to verify the notification content (see below)

JSON Example

{
  "scope": "badge",
  "action": "create",
  "sco_id": "12345",
  "sco_code": "course001",
  "badge_code": "beginner_badge",
  "score": "85",
  "user_id": "67890",
  "user_login": "sample_user",
  "user_email": "user@example.com",
  "datetime": "2024-01-15 10:30:45",
  "hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"
}

Hash Verification

  • Generated by concatenating each field with the secret key using | as delimiter, then hashing with SHA-256.
  • Concatenation order (must follow exactly): {scope}|{action}|{sco_id}|{sco_code}|{badge_code}|{score}|{user_id}|{user_login}|{user_email}|{datetime}|{secret}
  • Example (concatenated string): "badge|create|12345|course001|beginner_badge|85|67890|sample_user|user@example.com|2024-01-15 10:30:45|your_secret_key"
  • Notes:
  • secret is the "Secret Key" entered in the notification destination settings screen.
  • Incorrect concatenation order will cause verification to fail.