Create a notification endpoint
Proposes a new endpoint (notifications:manage): its name, format, filter and url. The platform stores the URL and never serves it back; the row carries its host and a fingerprint. Another member approves it before anything is sent, unless you are the organisation’s one member. Takes no If-Match. Answers 201 with the row.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Headers
Required on every write: a URL-safe string of 1 to 64 characters from [A-Za-z0-9._~-] (a UUID fits), scoped to you. It names one operation on one record, ever: a retry replays the stored outcome (Idempotent-Replay: true) or attaches to the live one, and reuse on another record refuses 409 IDEMPOTENCY_KEY_REUSED. Missing or malformed, 400.
Your own id for the request: 8 to 128 of [A-Za-z0-9._-]. It becomes the request’s id and is echoed on the response. A value off that grammar is replaced with a fresh id, never refused.
Query parameters
A position you hold — an X-Immix-Global-Sequence you read, or a 202’s commandGlobalSequence: this member answers only once it has folded the platform’s stream through it, waiting up to its deadline, then 503 PROJECTION_BEHIND with Retry-After. Within that stream a read is never older than what you have seen; drop your positions after an announced stream cut. A retry stating its 202’s position attaches to or replays that operation while the journal holds its key, never publishing twice. Stated once: one to nineteen digits, at most 9223372036854775807; else 400 MALFORMED_REQUEST.
Request
What the destination is sent. UNKNOWN is the unset sentinel: outputs only — as input the field is required, and explicit UNKNOWN refuses 400. A consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
The least urgent event to send. UNKNOWN is the unset sentinel: outputs only — as input the field is required, and explicit UNKNOWN refuses 400. A consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
The event types to send; at least one. a set (SBE bit-set) served as the array of its published names, each a NotificationEvent, in declared order; empty = none set, never null; as input a repeated name refuses 400
The endpoint’s name - 1 to 128 bytes of UTF-8.
The destination’s address — for SLACK, the incoming-webhook URL Slack issued. https, a host this environment sends to (hooks.slack.com), a path, and no port, user or fragment: anything else is 422 DESTINATION_NOT_ALLOWED. It is a secret: the platform stores it and never serves it back — the row carries host and urlFingerprint.
The algo instances to send events about - at most 64, each once and each an instance of the organisation; empty = every instance of the organisation. a repeating group served as an array of objects, in the group’s own order; empty = no entries, never null. Optional in this body: absent reads as [] — every instance.
A note for the approvers of this proposal; empty-not-null. At most 256 bytes of UTF-8. Optional in this body: absent reads as "".
Response
The endpoint exists: PENDING_APPROVAL while it waits for another member’s approval, ACTIVE at once where its maker is the organisation’s one member — with the answering change’s position, the row’s ETag and, on a replayed key, Idempotent-Replay.
The algo instances the endpoint is sent events about; empty = every instance of the organisation. It narrows the events that name an instance: one that names none - the organisation-wide halt - is sent whatever this list holds. a repeating group served as an array of objects, in the group’s own order; empty = no entries, never null
Who approved the row’s last proposal and when, in order. A proposal that waits concludes when the count reaches the organisation’s notifications approval rule, and never before one approval; the list is empty where the proposal concluded as it was made - its maker the organisation’s one member, or a deletion. a repeating group served as an array of objects, in the group’s own order; empty = no entries, never null
What the row’s last proposal proposed, kept once it concluded: ACTIVATE, AMEND or DELETE; NONE while it pends or when it was withdrawn. NONE is the unset sentinel: outputs only — as input the field is required, and explicit NONE refuses 400. A consumer READING this field treats an unknown name as NONE, never as an error; as input an unknown name refuses 400 — the parse is strict
The event types the endpoint is sent; never empty. a set (SBE bit-set) served as the array of its published names, each a NotificationEvent, in declared order; empty = none set, never null; as input a repeated name refuses 400
What the destination is sent: SLACK is a Slack message, posted to a Slack incoming-webhook URL. UNKNOWN is the unset sentinel: outputs only — as input the field is required, and explicit UNKNOWN refuses 400. A consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.
The destination’s host name alone - no scheme, port or path - at most 253 characters of lowercase letters, digits, dot and hyphen.
Why the last proposal was withdrawn, as the withdrawer stated it; empty-not-null.
The least urgent event the endpoint is sent: INFO sends every event, WARNING leaves INFO out, CRITICAL sends CRITICAL alone. UNKNOWN is the unset sentinel: outputs only — as input the field is required, and explicit UNKNOWN refuses 400. A consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
The endpoint’s name, as its organisation lists it - 1 to 128 bytes of UTF-8.
ACTIVATE or AMEND while a proposal waits for approval; NONE otherwise. While an AMEND waits, notifications are still sent as last approved. NONE is the unset sentinel: outputs only — as input the field is required, and explicit NONE refuses 400. A consumer READING this field treats an unknown name as NONE, never as an error; as input an unknown name refuses 400 — the parse is strict
The maker’s note on the last proposal, for its approvers; empty-not-null. At most 256 bytes of UTF-8.
PENDING_APPROVAL until the endpoint’s first proposal concludes - approved by another member, or made by the organisation’s one member - then ACTIVE, the one status notifications are sent in, then DELETED. A first proposal that was withdrawn leaves the row PENDING_APPROVAL with nothing pending. UNKNOWN is the unset sentinel: outputs only — as input the field is required, and explicit UNKNOWN refuses 400. A consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
The member behind this version. an actor: an object {kind, id}
The destination URL’s fingerprint as the gateway computed it when the URL was stored - enough to tell two URLs apart, never enough to rebuild one: fp- and sixteen lowercase hexadecimal digits.
The row’s version - monotonic, bumped on every change. int64 as a decimal JSON string
Platform time the row’s last proposal concluded - equal to proposedAtNs where it concluded as it was made; 0 while it pends or when it was withdrawn. int64 as a decimal JSON string
Who concluded it - the approver whose approval met the count, or the maker where it concluded as it was made; unstated when concludedAtNs is 0. an actor: an object {kind, id}; null where none is stated
Platform time of that withdrawal; 0 when none was. int64 as a decimal JSON string
Who made the last proposal that was withdrawn; unstated when none was. an actor: an object {kind, id}; null where none is stated
Who withdrew it - its maker, another member returning it, or the member whose deletion replaced it; unstated when none was. an actor: an object {kind, id}; null where none is stated
The maker of the row’s last proposal, kept after it concludes or is withdrawn - an approver is checked to be someone else while it pends. pendingTransition alone says whether a proposal pends. an actor: an object {kind, id}; null where none is stated