Skip to main content

​
Webhooks

Webhooks allow your systems to receive real-time notifications when events occur in Reading Steps.
Webhooks are currently in beta. Contact support@helpdesk.readingsteps.uk to request access.

​
Overview

When enabled, Reading Steps sends HTTP POST requests to your specified endpoint whenever certain events occur.

​
Setting up webhooks

  1. Go to Admin Panel > Integrations
  2. Click Webhooks
  3. Enter your endpoint URL
  4. Select which events to subscribe to
  5. Save and test the connection

​
Webhook payload

All webhooks are sent as JSON with this structure: 
{
  "event": "student.reading_completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": "org_abc123",
  "data": {
    // Event-specific data
  }
}

​
Available events

​
Student events

EventDescription
student.createdNew student added
student.updatedStudent details changed
student.archivedStudent archived
student.reading_completedStudent finished a reading session
student.level_changedStudent’s reading level changed

​
Class events

EventDescription
class.createdNew class created
class.updatedClass details changed
class.archivedClass archived

​
Assessment events

EventDescription
assessment.completedStudent completed an assessment
assessment.level_assignedReading level assigned from assessment

​
Event payloads

​
student.reading_completed

{
  "event": "student.reading_completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": "org_abc123",
  "data": {
    "student_id": "stu_xyz789",
    "student_name": "Emma Smith",
    "book_id": "book_123",
    "book_title": "The Adventure Begins",
    "reading_level": "3A",
    "duration_seconds": 420,
    "comprehension_score": 85
  }
}

​
student.level_changed

{
  "event": "student.level_changed",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": "org_abc123",
  "data": {
    "student_id": "stu_xyz789",
    "student_name": "Emma Smith",
    "previous_level": "2B",
    "new_level": "3A",
    "reason": "assessment_completed"
  }
}

​
assessment.completed

{
  "event": "assessment.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": "org_abc123",
  "data": {
    "student_id": "stu_xyz789",
    "student_name": "Emma Smith",
    "assessment_type": "placement",
    "score": 78,
    "recommended_level": "3A"
  }
}

​
Security

​
Verifying webhooks

Each webhook includes a signature header for verification: 
X-ReadingSteps-Signature: sha256=abc123...
Verify the signature using your webhook secret: 
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return `sha256=${expected}` === signature;
}

​
Webhook secret

Your webhook secret is displayed when you create the webhook endpoint. Store it securely and use it to verify incoming requests.

​
Retry policy

If your endpoint returns a non-2xx status code, Reading Steps retries:
AttemptDelay
1Immediate
21 minute
35 minutes
430 minutes
52 hours
After 5 failed attempts, the webhook is marked as failed and you’ll receive an email notification.

​
Best practices

  1. Respond quickly - Return a 200 status within 5 seconds
  2. Process asynchronously - Queue webhook data for background processing
  3. Handle duplicates - Use the event ID to deduplicate
  4. Verify signatures - Always verify the webhook signature
  5. Monitor failures - Set up alerts for webhook failures

​
Testing webhooks

Use the Test button in the webhook settings to send a test event to your endpoint. Test payload: 
{
  "event": "test",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": "org_abc123",
  "data": {
    "message": "This is a test webhook"
  }
}