# Signed event connection

Send POST /v1/integrations/events to the endpoint supplied by your private connection setup. Use V1 event version 1.0. The normalized JSON payload is bounded to 256 KiB.

Headers: X-Integration-Key-Id, X-Integration-Timestamp, X-Integration-Nonce, X-Integration-Signature.
Sign lowercase hex HMAC-SHA256 over five newline-separated fields: ISO request timestamp, unique nonce, uppercase method, exact request path without query, lowercase hex SHA256 of the exact transmitted body bytes. Request clock skew must be within five minutes.

Keep signing secrets in server-side runtime configuration. Hosted transport also needs the separately provisioned Access service credential. Never put secrets in URLs, public examples or marketing forms.

The credential binds workspace, system, integration, provider and allowed namespace. Generic events assert metadata.namespace_id; Eventus uses metadata.provider.namespace_id. Event IDs identify source work; request nonces identify transport attempts.

Retry an unchanged event body and ID with fresh timestamp, nonce and signature. Changed bytes under an existing ID are rejected. Reused nonces are rejected. Out-of-order source events must not regress terminal state.

Label setup and development events with metadata.test=true. A setup signal proves ingestion, not an operational run or a customer outcome.

401: verify active credentials, clock, exact bytes and transport authentication.
403: match the complete credential scope.
409: use a fresh nonce or investigate a conflicting event identity.
422: validate the event schema.
413: reduce the normalized payload.

Builder keys can be rotated/revoked in private account setup. Provisioned evaluation keys are managed by the workspace owner. Rotation invalidates the old key and requires updating runtime configuration.