Pause Status Webhook Handler
Component Detail
Description
Supabase database webhook that fires on INSERT or UPDATE of the status column in the peer_mentor_profiles table. Validates the payload, determines whether the transition is a pause or resume, and invokes the notification orchestrator. Runs as a Supabase Edge Function.
pause-status-webhook-handler
Summaries
The Pause Status Webhook Handler is the automated trigger that ensures no mentor status change goes unnoticed or unacted upon. Running as a serverless Supabase Edge Function, it listens directly to database-level changes, meaning coordinators receive timely notifications the moment a pause or resume occurs — without any manual intervention or polling delay. This real-time responsiveness is critical to maintaining coordinator confidence in the system: if status changes were missed or delayed, coordinators could make scheduling decisions based on stale information, creating downstream program disruptions. Automating this detection also removes a class of manual oversight tasks from coordinator workloads, freeing their time for higher-value mentorship support activities.
This component is the entry point of the pause notification pipeline and has a hard dependency on the `pause-notification-orchestrator`, which must be available before end-to-end testing can proceed. Development complexity is low, but deployment is slightly more involved than a standard backend service because it runs as a Supabase Edge Function with its own deployment pipeline and webhook registration step. The QA plan must include tests for payload validation failures, transition direction detection edge cases (e.g., status unchanged, unexpected status values), and orchestrator invocation failures. Integration testing requires a live or sandboxed Supabase environment with the webhook configured.
Timeline risk is low, but the webhook registration and Supabase Edge Function deployment process should be validated early to surface any environment-specific configuration issues.
Implemented as a Supabase Edge Function, this handler receives webhook POST events fired on INSERT or UPDATE of the `status` column in `peer_mentor_profiles`. The `validatePayload` function should check for required fields (`record.id`, `old_record.status`, `record.status`) and return a 400 response on failure. The `detectTransitionDirection` function maps status string pairs to a `TransitionType` enum (`PAUSE` | `RESUME` | `NO_CHANGE`) — the `NO_CHANGE` case must be handled explicitly to avoid spurious orchestrator invocations on unrelated column updates. The `extractPauseEvent` function assembles the `PauseEvent` domain object passed to the orchestrator.
Ensure idempotency: if the webhook fires twice for the same event (Supabase guarantees at-least-once delivery), the orchestrator should handle duplicate invocations gracefully, or this handler should implement deduplication using the event timestamp and mentor ID.
Responsibilities
- Listen for status column changes in peer_mentor_profiles via Supabase webhook
- Validate incoming webhook payload schema
- Detect transition direction (active→paused or paused→active)
- Invoke the pause notification orchestrator with the extracted event data
Interfaces
handleWebhookEvent(payload: WebhookPayload): Response
validatePayload(payload: WebhookPayload): Boolean
extractPauseEvent(payload: WebhookPayload): PauseEvent
detectTransitionDirection(oldStatus: String, newStatus: String): TransitionType