Integration Event

What It Models

Integration events describe information crossing the provider boundary. An incoming message preserves what arrived, an interpreted event carries meaning to applications, and an outgoing delivery represents one subscription’s projected copy of a Rhythm change. These records have separate processing outcomes even when they concern the same business operation.

Identity and Attributes

Endpoints and message, event and delivery records use generated identifiers. Endpoint address tokens identify ingress. Deduplication keys combine the endpoint with provider identity or body digest, or the subscription with the source change.

Endpoints retain account and kind, token address, registration method, provider reference, secret pointers and active, rotating or disabled status. Messages retain raw body and selected-header references, digest, verification and processing results, attempts, generated events and replay origin. Endpoint keys recognize provider event identifiers indefinitely and body digests for one day. Typed events retain source, subject, matched Rhythm context, data and routing outcome. Global declarations identify the application principal, consumer function and event types or prefixes handled. Subscriptions retain the installation, optional account, event interest, filter, push or pull mode and pause status. Deliveries retain projected payloads, attempts, errors, acknowledgement and pending, delivered, retrying, failed, dead or filtered status. Dispatch records carry webhook, routing or delivery work until their queues accept it.

Relationships

An endpoint and each received message identify one connection.. Disconnection disables endpoints while received-message history remains.. Each subscription names one installation and can select an individual account.. Uninstallation removes subscriptions while delivery history remains visible.. An asynchronous or unanswered call creates its applicable completion event.. Settlement writes that event and routing limits it to the initiating application..

Invariants

Webhook ingress saves the raw body and selected headers before recording its message and dispatch work or acknowledging receipt. Processing deduplicates an already processed provider event identifier without expiry and a body digest for one day; explicit replay bypasses those checks. The old and new signing secrets remain usable during the one-day rotation window. The router sends at most ten events per consumer invocation and can redeliver handled events; each consumer must recognize event identifiers. Completion routing selects the consumer belonging to the application that initiated the execution. Creating a subscription requires an enabled installation and an event type both declared by its current release and accepted by the customer. A subscription and change share one delivery identity, and its payload contains only the event projection’s allowed fields. Fifty successive dead deliveries pause an active subscription and request one administrator notice. Removing an event type from accepted access pauses active subscriptions atomically; restoring access does not resume them.

How It Is Stored and Shared

The integrations service owns endpoint, message, routing and subscription records. Raw notification bodies and selected headers are stored separately from database rows. Consumer declarations are global; message and delivery records belong to a workspace. The service exposes projected information rather than unrestricted business-record reads, and enables no custom fields.

Open Design Questions

The event milestone still needs Product’s acceptance decisions. Consumer retries require explicit deduplication obligations. Pull delivery exists separately from the unfinished synchronization-profile pages, and data-grant routes remain unimplemented.