Skip to content

BPPE Career

School Administrator

All sections
Ask Otto AI
Help

What is this page?

Communications API

Role aware

This page proves the communications API and outgoing webhook foundation: versioned endpoints, Zod schemas, OpenAPI components, event validation, webhook subscriptions, signing preview, and disabled delivery.

Audience
Staff
Current limits
The communications API proof uses local deterministic records only. It does not append communication events, mutate timelines, issue integration tokens, persist secrets, deliver webhooks, send notifications, write audit rows, or create provider deliveries.

Related Otto Guide links

Review communications APItaskCommunications API referencereferenceCommunicationsconceptPrivacy and securityconceptSettings, users, and rolesconceptOpen reference page placeholder

Support request boundary

Use Sev3 if endpoints, schemas, event validation, webhook signing preview, retry preview, or disabled production boundaries look incorrect; use Sev4 for labels or layout feedback. This panel does not submit a support case.

Sev1: Critical outage or data-risk emergency

Target: 1-hour response, 24/7 paging during pilot

Sev2: Major workflow blocked

Target: 4 business hours

Sev3: Standard product question or non-urgent issue

Target: 1 business day

Sev4: How-to, cosmetic, or future enhancement

Target: 2 business days

These preview controls are placeholders. Real AI answers, search, walkthroughs, and support submission come in later tickets.

Notifications17

Static proof preview

Real notification feeds, delivery, and preferences arrive in a later ticket.

Sam Director

Sam Director

sam.director@otto-fixture.test

Switch local proof role

StudentInstructorSchool Administrator

This changes only the local shell proof. Production role changes remain server-validated future work.

Search is a keyboard-focusable skeleton. No real index or permissioned search results are implemented in this ticket.

Communications - API

Communications API

Review communications event API contracts, append-only validation, outgoing webhook subscription previews, signed delivery previews, and disabled production writes.

Otto Fixture BPPE Career School - communications API

School Administrator · Sam Director

Communications API

Communications API and outgoing webhook foundation

Ticket 139 proves versioned communications JSON endpoints, Zod schema contracts, append-only event validation, outgoing webhook subscriptions, signed delivery preview, retry schedule preview, and proof-only write boundaries.

OpenAPI JSONEvents JSONWebhooks JSONStudent timeline

API version

v1

Versioned contract rooted under /api/v1/communications.

Events

5

Local event rows exposed for review.

Webhooks

2

Outgoing subscriptions stay preview-only.

Writes

0

Validation and delivery previews accept no writes.

Endpoint contract

Versioned JSON endpoints

List communication events

/api/v1/communications/events

GET
Behavior
read-only
Status codes
200, 400
Schemas
ListCommunicationEventsQuery, CommunicationEventListResponse, CommunicationsApiErrorEnvelope

Validate append-only event payload

/api/v1/communications/events

POST
Behavior
validation-preview
Status codes
200, 400
Schemas
CreateCommunicationEventRequest, CommunicationEventPreviewResponse, CommunicationsApiErrorEnvelope

List outgoing webhook subscriptions

/api/v1/communications/webhook-subscriptions

GET
Behavior
read-only
Status codes
200
Schemas
WebhookSubscriptionListResponse, CommunicationsApiErrorEnvelope

Preview signed outgoing webhook delivery

/api/v1/communications/webhook-subscriptions/{id}/test

POST
Behavior
delivery-preview
Status codes
200, 400, 404
Schemas
TestOutgoingWebhookRequest, WebhookDeliveryPreviewResponse, CommunicationsApiErrorEnvelope

Communications OpenAPI contract

/api/v1/communications/openapi

GET
Behavior
read-only
Status codes
200
Schemas
CommunicationEvent, WebhookSubscription, ListCommunicationEventsQuery

Schema registry

Zod-generated OpenAPI components

10 components

CommunicationEvent

WebhookSubscription

ListCommunicationEventsQuery

CreateCommunicationEventRequest

TestOutgoingWebhookRequest

CommunicationEventListResponse

CommunicationEventPreviewResponse

WebhookSubscriptionListResponse

WebhookDeliveryPreviewResponse

CommunicationsApiErrorEnvelope

POST /api/v1/communications/events

Append-only event validation

Dry run
{
  "personId": "person-maya-rivera",
  "type": "communication.message_sent",
  "channel": "in_app",
  "direction": "outbound",
  "sourceModule": "Student 360",
  "sourceRecordId": "student-360-compose-preview",
  "bodyPreview": "Reminder prepared from the Student 360 composer.",
  "idempotencyKey": "idem_139_comm_event_preview",
  "dryRun": true,
  "metadata": {
    "courseId": "course-med-120"
  }
}

POST /webhook-subscriptions/:id/test

Signed webhook delivery preview

No network call
{
  "eventType": "communication.delivery_failed",
  "sampleEventId": "comm-event-002",
  "idempotencyKey": "idem_139_webhook_preview",
  "dryRun": true
}

Outgoing webhooks

HMAC signing, retries, and delivery preview

Preview only

Signature

x-otto-signature with timestamp and v1 HMAC preview

Retries

1 minute, 5 minutes, and 30 minutes shown before queues exist

Delivery

delivery-preview with no network call

Proof boundary

Disabled production surfaces

No writes

Production communication event writes, timeline mutation, or source-record mutation

OAuth client credentials, integration scopes, tenant tokens, or public developer portal publishing

Webhook secret persistence, live signing keys, network delivery, retry queues, or delivery logs

Rate limits, ETags, cursor-token persistence, idempotency persistence, and request audit rows

Email, SMS, push, phone, mailbox capture, task creation, and notification delivery