🏠 Overview › ✅ Implementation Tasks ›✅ epic-pause-status-notifications-backend-pipeline-task-002

Scaffold Supabase Edge Function for webhook

epic-pause-status-notifications-backend-pipeline-task-002 — Create the Supabase Edge Function file structure for the pause status webhook handler. Set up the Deno entry point, configure the function to listen on the correct route, establish the HTTP request/response cycle, and wire up the Supabase webhook secret verification middleware.

critical priority low complexity infrastructure pending infrastructure specialist Tier 1

Acceptance Criteria

Edge Function directory exists at supabase/functions/pause-status-webhook/ with index.ts entry point
Function serves HTTP POST requests and returns 405 Method Not Allowed for all other HTTP methods
Webhook secret verification middleware reads WEBHOOK_SECRET from Deno.env and compares against the x-webhook-secret header (or HMAC signature header per Supabase convention)
Middleware returns HTTP 401 Unauthorized with JSON error body when secret is missing or does not match
Middleware returns HTTP 400 Bad Request with JSON error body when request body cannot be parsed as JSON
Function returns HTTP 200 OK with JSON acknowledgement body when secret verifies and body is valid JSON (stub handler for now)
supabase/config.toml or function-level config registers the function name correctly
Function can be deployed locally with supabase functions serve and reached via curl without errors
Environment variable WEBHOOK_SECRET is documented in .env.example (never committed with real value)
No hardcoded secrets anywhere in the codebase

Technical Requirements

frameworks
Deno
Supabase Edge Functions
apis
Supabase Edge Functions HTTP runtime
performance requirements
Cold start must complete in under 500ms
Secret verification must not add more than 2ms latency
security requirements
WEBHOOK_SECRET must be read exclusively from environment variables — never hardcoded
Use constant-time string comparison for secret verification to prevent timing attacks
Return generic error messages — do not reveal whether secret was missing vs wrong

Execution Context

Execution Tier
Tier 1

Tier 1 - 540 tasks

Can start after Tier 0 completes

Implementation Notes

Supabase Edge Functions run on Deno — use Deno.serve() (Deno 1.35+) rather than the older addEventListener('fetch') pattern. The Supabase webhook secret header is typically 'x-webhook-secret' but verify against the Supabase dashboard webhook configuration. For constant-time comparison use crypto.subtle.timingSafeEqual() with TextEncoder — do NOT use === for secret comparison as it is vulnerable to timing attacks. Structure the entry point as: (1) parse request, (2) verify method, (3) verify secret, (4) parse body, (5) delegate to handler (stub for now).

Keep index.ts thin — middleware logic should be extracted to middleware.ts for testability.

Testing Requirements

Manual integration test using supabase functions serve locally: (1) POST with correct secret and valid JSON body → 200, (2) POST with wrong secret → 401, (3) POST with no secret header → 401, (4) POST with valid secret but malformed JSON body → 400, (5) GET request → 405. Document these curl commands in a README or test script alongside the function. Automated Deno unit tests for the middleware function itself (inject mock Request objects).

Component
Pause Status Webhook Handler
infrastructure low
Dependencies (1)
Define TypeScript interfaces and Zod validation schemas for the Supabase database webhook payload received by the pause status webhook handler. Include peer_mentor_profiles INSERT and UPDATE event shapes, status column transition types (active→paused, paused→active), and error response types. epic-pause-status-notifications-backend-pipeline-task-001
Epic Risks (3)
medium impact medium prob technical

Supabase Edge Functions have cold start latency that may push coordinator notification delivery beyond the 5-second SLA, particularly during low-traffic periods when the function is not warm.

Mitigation & Contingency

Mitigation: Keep the Edge Function lightweight — delegate all heavy logic to the orchestrator layer and avoid large dependency bundles. Measure p95 end-to-end latency in staging and document actual SLA achievable.

Contingency: If cold start latency consistently breaches 5 seconds, introduce a keep-warm ping from the nightly-scheduler or document the actual p95 latency in the feature spec and adjust the acceptance criterion to reflect the realistic bound.

medium impact medium prob technical

Supabase database webhooks may fire duplicate events for a single status change under retry conditions, causing coordinators to receive multiple identical notifications for one pause event.

Mitigation & Contingency

Mitigation: Add idempotency checking in the webhook handler using the event timestamp and peer mentor ID. Store a notification dispatch record in the pause-status-record-repository and skip dispatch if a record for the same event already exists.

Contingency: If duplicates slip through in production, add a de-duplication filter in the notification centre UI layer so the coordinator sees at most one card per event, and implement a cleanup job for the notifications table.

medium impact low prob scope

A peer mentor with multi-chapter membership may have more than one responsible coordinator. The orchestrator design currently targets a single coordinator, and resolving multiple recipients may require schema changes to the org membership query.

Mitigation & Contingency

Mitigation: Review the multi-chapter-membership-service patterns before implementing the orchestrator's coordinator resolution. Design the dispatcher call to accept an array of coordinator IDs from the outset so adding multiple recipients is non-breaking.

Contingency: If multi-coordinator dispatch is out of scope for this epic, document the limitation and create a follow-up task. Default to the primary coordinator (lowest chapter hierarchy level) as the single recipient in the interim.

Quick Links
All Tasks Execution Plan