Webhooks

Receive real-time events as tutoring sessions progress.

Setup

curl -X POST https://api.evelynlearning.com/v1/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.com/webhooks/evelyn", "events": ["session.ended", "usage.summary"] }'

Payload Format

Example: session.ended

{
  "event": "session.ended",
  "timestamp": "2026-10-15T14:30:00Z",
  "partner_id": "algerian-bac",
  "data": {
    "session_id": "sess_abc123",
    "student_id": "stu_xyz789",
    "subject": "math",
    "topic": "quadratic-functions",
    "level": "11-12",
    "duration_seconds": 1847,
    "message_count": 24,
    "whiteboard_items": 8,
    "end_reason": "student_ended",
    "token_usage": {
      "input_audio_tokens": 14200,
      "output_audio_tokens": 21800,
      "input_text_tokens": 48500,
      "output_text_tokens": 18200
    },
    "estimated_cost_usd": 1.23,
    "metadata": {
      "class_id": "math-11b"
    }
  }
}

Events

15 events across 5 categories.

Session Lifecycle

Event	Trigger	Key Fields
`session.started`	Student begins tutoring	`session_id`, `student_id`, `subject`, `topic`, `level`, `input_mode`, `timestamp`
`session.active`	First student message sent	`session_id`, `student_id`, `timestamp`
`session.paused`	Student pauses session	`session_id`, `pause_reason`, `elapsed_seconds`
`session.resumed`	Student resumes session	`session_id`, `pause_duration_seconds`
`session.ended`	Session completes or times out	`session_id`, `duration`, `message_count`, `whiteboard_items`, `token_usage`, `end_reason`
`session.abandoned`	Student leaves without ending	`session_id`, `last_activity_timestamp`, `duration`
`session.transcript`	Full transcript available (post-session)	`session_id`, `transcript[]`, `whiteboard_commands[]`

Usage

Event	Trigger	Key Fields
`usage.summary`	End-of-session cost breakdown	`session_id`, `input_tokens`, `output_tokens`, `audio_tokens`, `estimated_cost`
`usage.daily`	Daily aggregate for partner	`date`, `total_sessions`, `total_minutes`, `total_cost`, `unique_students`

Content

Event	Trigger	Key Fields
`whiteboard.generated`	Whiteboard visual created	`session_id`, `command_type`, `page_number`, `timestamp`
`homework.uploaded`	Student uploads homework photo	`session_id`, `student_id`, `extraction_status`, `problem_count`
`homework.extracted`	Problems extracted from photo	`session_id`, `problems[]`, `confidence_score`

Learning

Event	Trigger	Key Fields
`student.milestone`	Student demonstrates mastery of a concept	`session_id`, `student_id`, `concept_id`, `milestone_type`

Errors

Event	Trigger	Key Fields
`error.session`	Session-level error	`session_id`, `error_code`, `error_message`, `recoverable`
`error.voice`	Voice engine error (connection, transcription)	`session_id`, `error_type`, `fallback_action`

Security

All webhooks are signed with HMAC-SHA256 using your webhook secret. Verify the X-Evelyn-Signature header before processing. See Authentication for verification code examples.

Retry Policy

Failed deliveries (non-2xx response) are retried with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 24 hours. After 5 failed attempts, the event is logged and available via GET /webhooks/:id/events.

*Testing

Use POST /webhooks/:id/test to send a test event and verify your endpoint is configured correctly.