02 - User Personas (Webhooks Module)
- 1. Tenant Developer — "Nadia" (primary)
- 2. School Admin / IT Coordinator — "Mr. Adeyemi"
- 3. Platform / Security Reviewer — "Dr. Okafor"
(forward-looking) - 4. Vendor DevOps — "Anjali"
(forward-looking) - Persona - screen mapping
- Notes
Personas that drive the Webhooks module surfaces. The module is a developer/integration tool: its primary users are technical. Derived from
src/modules/webhooks/**capabilities; nothing outside source is asserted.
1. Tenant Developer — "Nadia" (primary)
| Attribute | Detail |
|---|---|
| Role | Software developer / system integrator at the school (or vendor integrator on behalf of the tenant) |
| Context | Builds or maintains external systems (attendance hardware, SMS gateway, analytics, BI) that must react to StudyLyon events |
| Tools | API docs, Swagger (/api/v1/webhooks), webhook signing library, delivery logs |
| Permissions | webhook.create, webhook.read, webhook.update, webhook.delete (permissions.constants.ts:89-92) |
| Goals | Register an endpoint once; subscribe to exactly the events that matter; verify signatures (X-Webhook-Signature, HMAC-SHA256, webhook-delivery.worker.ts:70-82, 103-105); confirm deliveries land; retry failures |
| Frictions today | No event-type whitelist - free-form events: string[] (create-webhook.dto.ts:20-24); secret returned in plaintext by every CRUD read (webhooks.service.ts:31-47); logs capped at 50, unpaginated (webhooks.service.ts:88-93) |
| Success metric | Endpoint receives events reliably; signature verifies first time; delivery log shows green |
2. School Admin / IT Coordinator — "Mr. Adeyemi"
| Attribute | Detail |
|---|---|
| Role | Non-technical school administrator with elevated RBAC role |
| Context | Approves and operates vendor integrations that consume StudyLyon events |
| Permissions | webhook.read, webhook.update (pause/resume) |
| Goals | See which integrations are active; pause a webhook when a vendor behaves badly (POST /webhooks/:id/pause, webhooks.controller.ts:78-83); view delivery health without reading raw JSON |
| Friction today | No aggregate health surface beyond per-webhook metrics (webhooks.service.ts:142-156); failure reasons are raw responseBody strings (webhook-delivery-log.schema.ts:28-29) |
| Success metric | Can explain "why is this integration slow" from the metrics tile alone |
3. Platform / Security Reviewer — "Dr. Okafor" (forward-looking)
| Attribute | Detail |
|---|---|
| Role | Tenancy-wide auditor (platform admin bypasses tenant scope, base.repository.ts:20-30) |
| Context | Reviews signature schemes, secret handling, replay risk |
| Goals | Secret rotation policy; timestamped signatures |
| Friction today | Signature has no timestamp / replay window (webhook-delivery.worker.ts:103-105); no rotation endpoint (PATCH only, webhooks.controller.ts:39-43) |
| Status | Drives the security QA items in 14_QA_Checklist.md; persona is a stretch goal, not a shipped surface |
4. Vendor DevOps — "Anjali" (forward-looking)
| Attribute | Detail |
|---|---|
| Role | External SaaS provider consuming StudyLyon events (planned inbound public scope, IMPLEMENTATION_PLAN.md:48) |
| Context | Delivers their webhook to StudyLyon in the future (e.g. test-series integration, IMPLEMENTATION_PLAN.md:856) |
| Status | No receiver exists in source; surfaced only to scope (planned) work - not a current target persona |
Persona - screen mapping
| Persona | Screens (05) |
|---|---|
| Tenant Developer | 1 list, 2 create (event picker), 3 detail, 4 edit, 5 logs, 6 log detail, 7 test, 8 retry |
| School Admin | 1 list, 3 detail (metrics + pause/resume), 5 logs |
| Security Reviewer | 3 detail (secret), 14 QA items |
Notes
- The event picker must present the actual event types emitted by the platform
(
src/infrastructure/bullmq/event-queue-map.ts:6-43) - the API accepts any string, so the client is responsible for offering valid options (create-webhook.dto.ts:20-24). webhook.readgates both the webhook itself and its logs/metrics (webhooks.controller.ts:27-37, 52-56, 72-76) - no separate log permission.