Vision Developers
POST/calendar/v1/sync/webhooks/microsoft

Microsoft Graph change-notification URL

Public. Answers the validationToken handshake; otherwise authenticated per notification by clientState, and only schedules a sync. Items are validated before any database work, deduplicated by subscription, and at most ten subscriptions are handled per request; each subscription and each source is rate limited in-process.

App
Calendar
Contract
Calendar API 1.20.0
Lifecycle
preview
Runtime
restricted
Operation ID
receiveMicrosoftGraphNotification
Canonical origin
https://calendar.runonvision.com

Availability: This is a preview contract with runtime status restricted. Publication documents an approved interface; it does not imply public production access.

Purpose and use cases

Microsoft Graph change-notification URL

The owning App is Vision Calendar. Calendar owns scheduling resources, workspace and actor bindings, visibility, recurrence, conflict, and concurrency rules.

Request

POST https://calendar.runonvision.com/calendar/v1/sync/webhooks/microsoft

Authentication and authorization

No authentication requirement is declared for this operation.

Headers

  • Accept: application/json — recommended where a JSON response is declared.
  • Content-Type: application/json — required for the documented request representation.

Undeclared tracing, idempotency, conditional-request, and version headers are not assumed on this page.

Path and query parameters

NameLocationTypeRulesDescription
validationTokenquerystringoptional; maximum length 2048Not described in the contract.

Request body

Media type: application/json. The body is optional.

object

Runnable examples

Placeholder values are generated from the approved schema and are not live credentials or customer data. Replace every angle-bracket or shell variable value. Examples cannot be run until the App has a routed base URL and your client has the required grant.

cURL
curl 'https://calendar.runonvision.com/calendar/v1/sync/webhooks/microsoft' \
  --request POST \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{}'
JavaScript (server-side)
const response = await fetch('https://calendar.runonvision.com/calendar/v1/sync/webhooks/microsoft', {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
  },
  body: JSON.stringify({}),
}

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()
Python 3 standard library
import json
import urllib.parse
import urllib.request

request = urllib.request.Request(
    'https://calendar.runonvision.com/calendar/v1/sync/webhooks/microsoft',
    data=json.dumps({}).encode(),
    headers={
    "Accept": "application/json",
    "Content-Type": "application/json"
},
    method='POST',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

The current TypeScript reference client covers Platform token exchange and core reads. No native SDK helper is declared for this operation; use the HTTP contract directly and follow the SDK guidance.

Responses

StatusMeaningSchema
200validationToken echoedstring
202Receivednot specified
400Malformed validation tokennot specified
429Too many notifications from this source in the last minute. Nothing was processed.not specified

Success response schema

string
200 illustrative response
"<response>"

Errors and troubleshooting

Error bodies and codes are shown only where the approved contract declares them. Use status, the declared error schema, and any correlation identifier returned by the App; do not infer that two Apps share one envelope.

  • 400 — Malformed validation token
  • 429 — Too many notifications from this source in the last minute. Nothing was processed.

Collection behavior

Pagination: not declared. Filtering/search: not declared. Sorting: not declared.

Cursor lifetime, cursor binding, stable ordering, maximum traversal, and unknown-filter behavior are not assumed unless stated by a parameter description or schema constraint above.

Operational behavior

  • Rate limit: The operation declares 429, but the numeric policy is not in OpenAPI.
  • Retry: Retry only when the documented error model or response headers authorize it. Timeout and backoff values are not declared by this operation.
  • Idempotency: No idempotency header or replay window is declared.
  • Concurrency: No ETag, If-Match, or optimistic-version header is declared.

Security and privacy

  • Keep client credentials and bearer tokens on trusted servers.
  • Send only to the exact approved HTTPS origin and audience.
  • Treat response data according to the owning App's classification and retention policy; the OpenAPI contract does not itself grant data access.
  • Do not log credentials, tokens, complete private payloads, or secrets.

Edge cases and known documentation gaps

  • One or more parameters have no field-level description.
  • The request body has no purpose or conditional-rule description.
  • Business roles, timeout, retry budget, rate value, idempotency window, and concurrency behavior are absent unless explicitly stated above.

Contract history and evidence