Connector ingest

The HMAC-signed endpoints a store plugin calls — thin signals, heartbeats and the profile doorway.

The plugin has two roles and keeps no business logic. Operation-level detail (schemas, responses) is in the Control-plane API under the Connector Ingest tag; this page explains how the pieces fit.

Role 1 — signalling (outbound)

Thin events, fat pull. The plugin tells Sarvex that something changed; Sarvex pulls the full entity.

POST /connector/signals carries only the entity type, id, timestamp and a monotonic sequence — never payment credentials or PII.

Header	Meaning
`X-Sarvex-Signature`	HMAC-SHA256 over the raw body plus the two headers below, keyed by the per-connector secret issued at pairing.
`X-Sarvex-Timestamp`	Request time.
`X-Sarvex-Sequence`	Monotonic sequence; a seen sequence is rejected `409` (replay / out of order).
`Idempotency-Key`	Safe retries.

A 202 means accepted for asynchronous processing. A dropped signal is caught by Sarvex’s sweeper, so the plugin sends asynchronously with a hard timeout and a local retry.

POST /connector/heartbeat reports plugin liveness (204).

Role 2 — profile doorway (inbound)

GET /connector/profile returns the exact UCP profile bytes Sarvex generates and signs. The plugin serves them verbatim at /.well-known/ucp on the merchant’s own domain with a 200 (never a redirect).

Send If-None-Match with the last ETag; unchanged → 304.
Cache-Control says how long the copy is valid. If Sarvex is unreachable, serve the last-known-good copy.
The merchant is resolved from the HMAC credential — no URL parameter.

The plugin does not proxy the UCP API: the profile’s services.endpoint points directly at Sarvex.

Pairing

After install the plugin pairs with Sarvex to obtain its signing secret; see the pairing guide.