Ellucian Ethos change events → outbound webhooks

// pull change-notifications, resolve, forward as a normalized webhook
GET /consume?limit=100  // Ethos change-notifications
// for each change:
GET /api/{resource}/{id}  // resolve current representation
POST https://your-hub/webhooks/ethos
{
  "resource": "student-registrations",
  "id": "…",
  "op": "changed",
  "data": { … }
}

How we'd take this from discovery to a production-safe cutover — the phases, the canonical mapping, and the edge cases that bite.

Subscribe to Ellucian Ethos change-notification events and re-publish them as deduplicated, fan-out webhooks to downstream consumers. This replaces polling of Banner (or Colleague) tables with an event-driven pipeline.

Implementation Phases

1. Discovery & inventory: Enumerate the Ethos resource types (e.g., persons, courses, sections, academic-loads) your downstream systems need. Pull the current Ethos API OpenAPI spec (available at /api/core/{{version}}/openapi.json) to confirm the change-notification schema for each. List every downstream consumer (Banner table triggers, LMS plugins, identity providers) and decide which events each requires.
2. Subscription configuration: In the Ethos Admin console, create one or more change-notification subscriptions. Set eventTypes to [CREATE, UPDATE, DELETE] for each required resource type. Target a single receiver endpoint: https://{{your-host}}/api/v1/ethos-events/inbound. Enable includeChangedFields: true to surface only modified attributes. Record the subscriptionId for audit and revocation.
3. Receiver service: Build a stateless HTTP receiver that accepts Ethos change payloads. Validate the shared X-Ethos-Signature HMAC header (compute HMAC-SHA256(secret, rawBody) and compare). Acknowledge with 202 Accepted immediately; do not process synchronously. Persist the raw event to a durable queue (Azure Service Bus, AWS SQS, or Redis Streams) before responding.
4. Deduplication layer: Ethos guarantees at-least-once delivery and can emit duplicate events under failover. Before enqueuing, compute a deduplication key: {{subscriptionId}}:{{eventId}}. Store keys in Redis with a 24-hour TTL (matching Ethos's replay window). Reject any event whose key already exists with 409 Conflict logged as a benign duplicate.
5. Fan-out dispatcher: Maintain a registry of downstream webhook subscriptions (endpoint URL, required resource types, auth method, retry policy). On dequeue, consult the registry and emit one webhook per matching consumer. Sign payloads with an HMAC using each consumer's shared secret. Send with exponential back-off: attempts at 0s, 30s, 2m, 10m, 1h. After 5 failures, move to a dead-letter queue and alert.
6. Testing & parallel run: Use Ethos's built-in event simulator (or Postman against the receiver) to fire create/update/delete payloads. Assert that: (a) duplicates are rejected, (b) each registered consumer receives exactly one webhook per event, (c) payload contains eventId, resourceType, resourceId, eventType, timestamp, and changedFields. Run the pipeline in shadow mode first: emit webhooks to a test endpoint but do not trigger downstream actions.
7. Cutover: Decommission any Banner table triggers or polling jobs for the covered resource types only after a 48-hour parallel run shows zero divergence between Ethos events and prior data. Keep the old polling path dormant for 30 days as a rollback path. On go-live, flip the Ethos subscription from test to production scope and enable webhook delivery to live endpoints.

Canonical Field Mapping

Edge Cases

• Duplicate delivery: Ethos may re-deliver the same eventId under broker restart or network timeout. If deduplication is absent, downstream systems may apply UPDATE twice, corrupting audit columns. Always check the key store before processing.
• Out-of-order events: A later CREATE may arrive before an earlier UPDATE for the same resourceId. Downstream systems that maintain a local cache must treat event.occurredAt as the ordering authority, not arrival sequence.
• DELETE before CREATE (race on first sync): If a consumer starts mid-stream, a DELETE event may arrive for a resource the consumer has never seen. Consumers must treat missing local state gracefully — do not throw on unknown resource ID for DELETE.
• High-volume burst: Bulk data loads in Banner can flood Ethos with hundreds of change events per second. The receiver must absorb without returning 429; queue depth must be monitored and autoscaling triggered above 80% capacity.
• Webhook endpoint churn: Downstream services may rotate their own TLS certificates or change ingress paths without notice. Treat HTTP 410 Gone as a signal to deactivate the subscription and alert ops before events are lost.
• Partial field coverage: Ethos may emit a change event that lists a changedFields entry not present in the consumer's expected schema (e.g., a Banner extension attribute). Webhook consumers must ignore unknown keys rather than reject the entire payload.

Cutover

Make the transition reversible by keeping the legacy Banner trigger or polling path dormant, not deleted, for 30 days post-go-live. During the rollback window, if webhook-based data diverges from the polling baseline by more than a configurable threshold (e.g., 0.1% of records for a given resource type), halt the Ethos subscription and re-enable polling automatically. Use a reconciliation report that joins resourceId from Ethos events against the Banner source table on PIDM, flagging any resourceId that has no matching polling record within the same event window. Only decommission the polling path after two consecutive clean reconciliation runs. Maintain an event-sourced audit log of every webhook emitted, including delivery status and retry count, to prove data completeness to auditors.