Webhooks

Receive real-time notifications when events occur in DNLearn.

Overview

Webhooks send HTTP POST requests to your server when:

• Users are created or updated
• Enrollments change
• Grades are posted
• Courses are modified
• Assignments submitted

Setting Up Webhooks

Create Webhook

POST /api/v1/webhooks
{
  "url": "https://your-server.com/webhook",
  "events": ["enrollment.created", "grade.updated"],
  "secret": "your_secret_key"
}

Configure Endpoint

Your endpoint should:

• Accept POST requests
• Return 200 status quickly
• Verify signatures
• Process asynchronously

Event Types

User Events

• user.created
• user.updated
• user.deleted

Course Events

• course.created
• course.updated
• course.published
• course.archived

Enrollment Events

• enrollment.created
• enrollment.updated
• enrollment.deleted

Grade Events

• grade.created
• grade.updated
• submission.created

Assignment Events

• assignment.created
• assignment.due
• assignment.submitted

Payload Format

{
  "id": "evt_xxxxx",
  "type": "enrollment.created",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "courseId": "course_xxx",
    "userId": "user_xxx",
    "role": "student"
  }
}

Verifying Signatures

Verify requests are from DNLearn:

const signature = req.headers['x-dnlearn-signature'];
const expected = crypto
  .createHmac('sha256', secret)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid signature');
}

Retry Policy

Failed deliveries are retried:

• Immediate retry
• 5 minutes
• 30 minutes
• 2 hours
• 24 hours

After 5 failures, webhook is disabled.

Monitoring

View webhook activity:

• Delivery attempts
• Response codes
• Error messages
• Retry status