Webhook Receiver

Canvas FHIR bridge. Bidirectional. Receives Canvas webhooks on one side, pushes back to Canvas on the other. The only service with Canvas webhooks pointed at it.

Overview

Webhook-receiver is the Canvas-platform boundary. It does two jobs:

• Ingress. Canvas POSTs FHIR events (e.g. MedicationRequest.activated, Appointment.booked) to our public endpoint. We HMAC-verify, persist verbatim, normalize into our internal event envelope, and emit to EventBridge.
• Egress. Our internal services emit events like patient.archived. A SQS-backed CanvasSyncWorker consumes these and writes back to Canvas via canvas-client, with strong idempotency and typed-error-based disposition.

Status

Ingress: Canvas → us

The POST /webhooks/canvas endpoint is the sole Canvas-facing entrypoint.

Flow

1. Canvas POSTs to /webhooks/canvas with header X-Canvas-Signature.
2. We read the raw body (before any JSON parsing).
3. We INSERT a canvas_webhook_events row immediately — before deciding whether the signature is valid. This is a deliberate forensic choice: even invalid payloads are captured.
4. HMAC verify via @yourera/canvas-client's verifyCanvasWebhook. signature_valid is persisted as the result.
5. If signature_valid = false: log a structured warn (CloudWatch Metric Filter hook) and return 401. Do NOT dispatch. The row is retained for forensics.
6. If valid but malformed JSON: persist, log, return 400. No dispatch.
7. Otherwise: parse, normalize into the canonical envelope, INSERT an outbox row with the normalized event, update canvas_webhook_events.dispatched_outbox_id to link them.
8. Return 200. Outbox worker ships the event to EventBridge.

Event naming

Canvas webhooks carry a FHIR resource type and an action. We emit internal events as canvas.{resource_snake}.{action}:

Consumers filter via EventBridge rules on source=canvas + detail-type. No fan-out is done at the emitter side — webhook-receiver just publishes; rules route.

Egress: us → Canvas

Internal events (e.g. patient.archived) fan out via EventBridge. An SQS queue owned by webhook-receiver has an EventBridge rule subscription for the events that need to write back to Canvas. The CanvasSyncWorker consumes the queue.

Flow

1. Worker polls SQS. Receives a message with the envelope.
2. Computes an idempotency key (see Idempotency Key).
3. UPSERT into canvas_sync_attempts keyed by the idempotency key. If existing row is terminal (succeeded, failed, abandoned), ack and move on.
4. Atomically bump attempts++ via SQL expression (race-safe; two workers cannot double-count).
5. Dispatch to the appropriate handler. For Phase 1, the only handler is patient.archived → canvas-client.patient.update(id, { active: false }).
6. Disposition based on the result (see Error Disposition).

Database Schema

canvas_webhook_events (ingress log)

Immutable audit log of every Canvas webhook we received, valid or not.

canvas_sync_attempts (egress ledger)

Per-egress-work-unit ledger with idempotency key.

Also present: outbox and audit_events, shared-pattern tables.

HTTP Endpoints

Event Contracts

Defined in @yourera/contracts/events/canvas.ts. The canonical envelope for every Canvas-origin event we emit:

export const canvasEventEnvelopeSchema = z.object({
  webhookEventId: z.string().uuid(),
  canvasEventName: z.string(),      // e.g. "MedicationRequest.activated"
  resourceType: z.string(),         // e.g. "MedicationRequest"
  resourceId: z.string(),
  canvasEventTimestamp: z.string().datetime(),
  receivedAt: z.string().datetime(),
  resource: z.unknown(),             // the FHIR resource body as received
});

Consumers use EventBridge rules with detail-type = canvas.{resource_snake}.{action}. For example, orchestrator subscribes to canvas.medication_request.activated; pharmacy-router subscribes to canvas.medication_dispense.completed.

Idempotency Key

The egress idempotency key is deterministic from (internal event name, target resource id, intent). For patient.archived the shape is:

canvas-sync:patient.archived:canvasPatientId:<canvasPatientId>:active=false

The canvas_sync_attempts.idempotency_key column has a unique index. Two concurrent workers receiving the same SQS message (or a re-delivery after an ack timeout) collide on INSERT and short-circuit.

Error Disposition

The CanvasSyncWorker branches on the error class returned from canvas-client:

Testing

841 tests:

• 535 unit — ingress parsing, signature verification hooks, envelope normalization, error-disposition branching, idempotency key derivation.
• 302 integration — end-to-end ingress and egress with canvas-client stubbed; outbox and attempts ledger verified.
• 9 real-Postgres-skipped — run locally for the atomic attempts-counter update, idempotency-key unique-index collision behavior, and concurrent worker races.

TODOs & Future Waves

• More egress handlers. Phase 1 is only patient.archived. Forthcoming: physician membership grants routed to Canvas Task assignments; saga-abort MedicationRequest cancellation; consent revocation pushback.
• Ingress fan-out to orchestrator. canvas.medication_request.activated needs to kick the saga. The subscriber lives in orchestrator, not here — webhook-receiver only emits.
• Dead-letter visibility. SQS DLQ is configured; a first-class admin UI for DLQ inspection is pending.
• Canvas-side subscription management. Webhooks are configured in the Canvas console today. Programmatic registration via FHIR Subscription resource is a Wave C item; requires canvas-client to add the wrapper.
• PHI retention policy for canvas_webhook_events. Currently retained indefinitely. Need legal-approved retention + pruning job.
• CloudWatch alarms. The structured warn on signature-failure has a metric filter hook wired; the alarm threshold + routing is a follow-up.