Update a notification endpoint
Proposes an amendment (notifications:manage): the name, format and filter restated whole, and url only to change the destination. What was last approved stays in force until another member approves this. Re-sent while a proposal waits, it replaces that proposal and clears its approvals.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
The record’s id — a positive 32-bit integer the platform minted.
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.
Required on every entity write: the ETag the read minted, quoted or bare — the version this write was computed against — or * to write unconditionally on purpose, except on a notification endpoint’s approval, which refuses * 400 INVALID_IF_MATCH. Absent is 428 PRECONDITION_REQUIRED; a weak validator 400 INVALID_IF_MATCH; a stale value 412 VERSION_CONFLICT (CONFIG_SEQ_CONFLICT on an algo’s config write) with currentVersion and a fresh ETag: re-read, reapply, retry. A * write overwrites every field from your copy, a colleague’s amend since your read included.
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.
0 = create.
The row version this amendment was written against; 0 = whatever it is now. Not read on a create. int64 as a decimal JSON string
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 "".
A new address for the destination; absent keeps the one the endpoint has. The same rules as on the create: https, a host this environment sends to, a path, and no port, user or fragment (422 DESTINATION_NOT_ALLOWED). A secret, stored and never served back.
Response
The notification endpoint as the platform now holds it after the write — the same row the read serves, 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