Webhooks API
Real-time notifications and event-driven integrations for your Klasstra system.
Available Webhook Events
student.created
Triggered when a new student is created
{
"event": "student.created",
"timestamp": "2024-01-15T10:30:00Z",
"data": {
"id": 123,
"student_id": "STU001",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"class_id": 456,
"status": "active"
}
}student.updated
Triggered when student information is updated
{
"event": "student.updated",
"timestamp": "2024-01-15T14:30:00Z",
"data": {
"id": 123,
"student_id": "STU001",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"class_id": 456,
"status": "active",
"changes": {
"email": {
"old": "john.doe@oldemail.com",
"new": "john.doe@example.com"
}
}
}
}grade.submitted
Triggered when grades are submitted for an assignment
{
"event": "grade.submitted",
"timestamp": "2024-01-15T16:45:00Z",
"data": {
"assignment_id": 501,
"course_id": 101,
"course_name": "Algebra I",
"teacher_id": 201,
"grades_count": 25,
"due_date": "2024-01-20"
}
}attendance.marked
Triggered when attendance is marked for a class
{
"event": "attendance.marked",
"timestamp": "2024-01-15T09:15:00Z",
"data": {
"class_id": 301,
"course_id": 101,
"date": "2024-01-15",
"teacher_id": 201,
"attendance_summary": {
"present": 23,
"absent": 2,
"late": 1,
"total": 26
}
}
}course.created
Triggered when a new course is created
{
"event": "course.created",
"timestamp": "2024-01-15T11:00:00Z",
"data": {
"id": 102,
"course_code": "SCI201",
"course_name": "Biology",
"subject": "Science",
"grade_level": "Grade 10",
"teacher_id": 202,
"class_id": 302,
"status": "active"
}
}user.login
Triggered when a user logs into the system
{
"event": "user.login",
"timestamp": "2024-01-15T08:30:00Z",
"data": {
"user_id": 201,
"user_type": "teacher",
"email": "teacher@example.com",
"ip_address": "192.168.1.100",
"user_agent": "Mozilla/5.0..."
}
}Webhook Management API
POST
/webhooks
Create a new webhook endpoint
Parameters
url(string)Required
Webhook endpoint URL
events(array)Required
Array of events to subscribe to
secret(string)
Secret key for signature verification
active(boolean)
Whether webhook is active (default: true)
Response
{
"id": "wh_1234567890",
"url": "https://your-app.com/webhooks/klasstra",
"events": ["student.created", "student.updated"],
"secret": "whsec_1234567890abcdef",
"active": true,
"created_at": "2024-01-15T10:30:00Z",
"last_triggered": null
}GET
/webhooks
List all webhook endpoints
Parameters
active(boolean)
Filter by active status
Response
{
"data": [
{
"id": "wh_1234567890",
"url": "https://your-app.com/webhooks/klasstra",
"events": ["student.created", "student.updated"],
"active": true,
"created_at": "2024-01-15T10:30:00Z",
"last_triggered": "2024-01-15T14:30:00Z",
"success_count": 45,
"failure_count": 2
}
]
}PUT
/webhooks/{id}
Update webhook endpoint settings
Parameters
id(string)Required
Webhook ID
url(string)
Updated webhook URL
events(array)
Updated event subscriptions
active(boolean)
Updated active status
Response
{
"id": "wh_1234567890",
"url": "https://your-app.com/webhooks/klasstra",
"events": ["student.created", "student.updated", "grade.submitted"],
"active": true,
"updated_at": "2024-01-15T15:30:00Z"
}DELETE
/webhooks/{id}
Delete a webhook endpoint
Parameters
id(string)Required
Webhook ID
Response
{
"message": "Webhook successfully deleted",
"id": "wh_1234567890"
}Security & Reliability
Signature Verification
Verify webhook authenticity using HMAC signatures
// Node.js example
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}Retry Logic
Automatic retry for failed webhook deliveries
- Exponential backoff strategy
- Maximum 3 retry attempts
- Retry intervals: 1s, 5s, 30s
- Failed webhooks logged for debugging
Real-time Delivery
Immediate webhook delivery for critical events
- Sub-second delivery for most events
- Guaranteed delivery within 5 seconds
- Event ordering preserved
- Duplicate detection and prevention
Best Practices
Webhook Implementation
- Always verify webhook signatures
- Implement idempotency for duplicate events
- Respond quickly (within 5 seconds)
- Log all webhook events for debugging
Error Handling
- Return appropriate HTTP status codes
- Handle network timeouts gracefully
- Monitor webhook delivery success rates
- Set up alerts for failed deliveries
Start Building with Webhooks
Set up your first webhook and start receiving real-time notifications.