# Customer-owned integration gateway and field redaction

Source: https://frosvo.com/docs/customer-owned-integration-gateway
Updated: 2026-11-08

Connect Frosvo to an HTTPS integration gateway you host, enforcing narrow allowlisted lookup schemas and automatic sensitive-field redaction.

Security-conscious teams often want the chat widget or support desk to look up order, invoice, or service status from internal systems without exposing broad CRM endpoints or risking sensitive fields entering support logs. Frosvo's **Customer-owned integration gateway** lets you route structured lookups through an HTTPS endpoint you control, complementing [regional data placement](/docs/regional-data-placement) and [Slack and the account connector](/docs/slack-and-account-connector).

## Configuring your gateway in the Desk

Workspace owners configure the gateway under **Settings → Integrations → Actions in your system → Customer-owned integration gateway**:

1. Enter a descriptive gateway name and your HTTPS endpoint URL (for example, `https://gateway.example.com/frosvo`). Loopback, private network, and non-HTTPS URLs are automatically refused.
2. Save the endpoint and securely copy the signing secret shown once. Configure that same secret on your gateway. Frosvo seals its stored copy; custom authentication headers are not part of this integration.
3. Tick the exact schemas your gateway permits:
   - `order.lookup` — used by [visitor order tracking](/docs/visitor-order-and-service-tracking) and desk order checks.
   - `ticket.status` — used for external ticket status lookups.
   - `service.status` — used for service health or provisioning checks.
   - `invoice.lookup` — used for billing reference checks.

## Automatic sensitive-field redaction

Frosvo accepts only exact-reference tracking records with bounded `reference`, `title`, `status`, `subtitle`, `url` and `observedAt` fields. Unknown fields are discarded. Additional redaction settings can hide permitted fields. This does not classify secrets embedded inside otherwise permitted text: your adapter must return customer-safe content. Detail links must be public HTTPS addresses without embedded credentials or authentication tokens.

## Verifying gateway signatures and monitoring health

When you save your gateway for the first time (or click **Rotate signing secret**), Frosvo displays your HMAC-SHA256 signing secret. Verify `Frosvo-Signature` over `{timestamp}.{rawBody}`. **Test connection** sends an authenticated ping and reports latency or a sanitized error; it does not prove source-system ownership checks.

## Protocol and configuration changes

Deploy the application and reference gateway with protocol `1.1` together. Responses must echo `requestId`, `scope` and `subjectHash`, declare `version: "1.1"`, and include a current ISO `checkedAt`. A lookup returns at most five `items`. `observedAt` is the source record's actual update time; omit it when unknown. Old or mismatched envelopes are refused. The reference runtime constructs this envelope for your adapter.

Choose scopes explicitly; the default grants none. Requests require an exact reference and a verified customer identity. Your adapter must independently authorize that identity against the exact source object. An email typed into chat is not verification.

Settings edits and secret rotation compare the saved configuration version. If another owner changes it, reload saved settings before retrying. Reload replaces unsaved edits and clears the displayed one-time secret. Coordinate rotation with your gateway deployment; lookups fail until both sides use the same key. Results arriving after a configuration change are discarded.

The supplied Node runtime lives in `integrations/customer-gateway/`. You must supply the source adapter, public TLS endpoint, traffic limits and monitoring. It bounds source concurrency and response time, passes an AbortSignal to the adapter, and retains capacity for timed-out work until that work actually stops. Configure upstream database/query deadlines as well.

Its default replay cache is process-local. For restarts or multiple instances, configure `FROSVO_GATEWAY_REPLAY_GUARD` with your shared durable store's atomic claim implementation; the runtime README documents the contract, retention and failure behavior. Store outages fail closed. The interface does not provision or verify your storage implementation. Test concurrent claims, restart survival, expiry, rotation and outages in your deployment. A saved endpoint is not a deployed customer gateway.

For gateway processes on one host, the supplied `sqlite-replay.cjs` offers durable local replay storage without a paid service. It requires a tested Node runtime with `node:sqlite`. Initialize a private persistent file once, then configure `FROSVO_GATEWAY_REPLAY_DB` and a stable `FROSVO_GATEWAY_REPLAY_NAMESPACE`. Normal startup refuses missing or corrupt retained state rather than resetting it. Keep the same file and namespace through restarts and signing-key rotations. Do not place this store on a network filesystem or share it across hosts. The runtime README contains exact setup and acceptance commands; your TLS endpoint and source adapter still need deployment verification.

For a hosting pilot, a supplied [WHMCS read-only adapter](/docs/whmcs-visitor-tracking) supports the four tracking scopes. Its credential and verified identity mapping are separate from the agent-facing WHMCS plugin. Controlled source-system acceptance remains required.

## Common questions

### How is the customer-owned integration gateway different from the general account connector?

The gateway allows four read-only scopes and accepts only a validated response envelope with explicitly permitted tracking fields. Unknown response fields are discarded.

### How can our gateway verify that a request genuinely came from Frosvo?

Verify the Frosvo-Signature header, formatted t=timestamp,v1=digest. The HMAC-SHA256 input is timestamp, a dot, and the exact raw request body. Use the workspace gateway signing secret.
