Security

Every request crossing the trust boundary is signed, every secret is stored encrypted at rest, and every scope is the minimum needed to make a feature work.

Trust Boundary

Side	What it controls	What it cannot do
HubSpot account	Approve or revoke the OAuth grant; configure the workflow action; uninstall the app.	Read or modify another connected account’s data; impersonate Chert; bypass the signature requirement on inbound webhooks.
Chert	Use the granted scopes; refresh tokens; create Communication engagements on contacts the customer’s app has access to.	Read deals, companies, tickets, custom objects, or any contact property outside the documented mapping.

The boundary runs along the OAuth grant. Revoking the grant in HubSpot — or disconnecting from the Chert console — is sufficient to end Chert’s access to the account.

OAuth Scopes

Each scope is the least-privilege scope that makes its feature work.

Scope	Used by	Why this scope and not a broader one
`oauth`	Token exchange and refresh	HubSpot requires this scope on every public app that uses OAuth.
`crm.objects.contacts.read`	Sidebar card, workflow action, contact-creation webhook	Reads `phone`, `mobilephone`, `firstname`, `lastname`, and `company` on the targeted contact only. No bulk read of the contacts collection.
`crm.objects.contacts.write`	Reply push	Creates Communication engagements and associates them to the contact. Chert never updates contact properties.
`crm.schemas.contacts.read`	Sidebar card	Resolves the contact schema in accounts with custom property layouts so reads work without per-account configuration.
`automation`	Workflow custom action	Registers the custom action and accepts its callbacks. Chert does not read, modify, or trigger workflows it did not register.

Chert does not request scopes for deals, companies, tickets, custom objects, files, marketing email, ads, or social.

HubSpot Signature v3

Every webhook and every fetch from the sidebar UI extension carries HubSpot’s v3 signature. Chert verifies the signature before any database work and before parsing the request body.

Component	Detail
Header	`X-HubSpot-Signature-v3`, base64-encoded HMAC-SHA256.
Header	`X-HubSpot-Request-Timestamp`, Unix milliseconds.
Skew bound	Reject when the timestamp differs from server time by more than five minutes.
HMAC input (POST)	`${method}${decodedRequestUri}${rawBody}${timestamp}`
HMAC input (GET)	`${method}${decodedRequestUri}${timestamp}` — the body is omitted entirely, not included as an empty string.
Key	The app’s client secret.
Comparison	Constant-time.

The request URI is URL-decoded before hashing and includes the full scheme, host, path, and query string.

The GET signature shape is a frequent source of integration bugs. HubSpot signs GETs without any body segment — a GET signature computed over ${method}${uri}${""}${timestamp} will always disagree.

The install flow uses a short-lived signed cookie to bind the OAuth state parameter to the originating Chert project.

Property	Value
Cookie name	`hubspot_oauth_state`
TTL	10 minutes
HttpOnly	Yes
Secure	Yes in production
SameSite	`lax`
Signature	HMAC-SHA256 of the JSON payload, keyed by the app’s client secret

The callback rejects the request if the cookie is missing, the signature does not match, the embedded state does not match the URL state, or the timestamp is older than the TTL.

Token Storage

Secret	Where it lives	At rest
HubSpot client ID	Chert environment variables	Standard environment-variable storage
HubSpot client secret	Chert environment variables	Standard environment-variable storage
Per-account access token	`hubspot_tenants.access_token`	Encrypted at rest by the database provider
Per-account refresh token	`hubspot_tenants.refresh_token`	Encrypted at rest by the database provider

Refresh tokens rotate on every refresh — the helper persists the new value before returning. Stale refresh tokens are not retained. The Chert console never exposes access or refresh tokens in any UI or API response. The admin dashboard surfaces only the granted scopes, the token expiry, and the per-tenant counters.

Data Handling

Data	Read	Stored	Retention
Contact `phone` and `mobilephone`	Yes	On the resolved Chert lead row	Same retention as other Chert lead data
Contact `firstname`, `lastname`, `company`	Yes, when auto-creating	On the lead row	Same retention as other Chert lead data
Outbound message text	Sent through Chert’s pipeline	On the conversation row, plus a 500-character preview on `hubspot_send_events.request_payload` for support	Conversation rows follow the project’s retention policy; event log rows roll off after 90 days
Inbound reply text	Pushed to HubSpot as a Communication body	On the conversation row	Same as outbound
HubSpot Communication ID	Returned by the create call	Implicit in the engagement on the contact timeline	Lives in HubSpot

Chert does not log full request or response bodies for HubSpot calls beyond the 500-character preview noted above. PII fields are redacted in error logs by server-side sanitization.

Sub-processors

Sub-processor	Purpose
HubSpot, Inc.	Authoritative source for contact data and the destination for reply pushes.
Vercel, Inc.	Hosts the Chert console and API.
Supabase, Inc.	Hosts the encrypted database that stores tenant rows, leads, conversations, and the event log.
OpenAI, L.L.C.	Optional AI-drafting of messages when the account has the feature enabled. The HubSpot integration does not require AI drafting.

The current sub-processor list is published at https://trychert.com/legal/sub-processors.

Incident Response

Event	Action
Suspected token leak	Disconnect the affected HubSpot account from the Chert console, then re-install. The disconnect flips the tenant inactive and invalidates the cached tokens; the re-install rotates them.
Lost client secret	Rotate the secret in HubSpot’s developer dashboard. Chert’s environment is updated, then every connected account refreshes its tokens on the next call. Existing access tokens remain valid until they expire naturally.
Stuck circuit breaker	The per-tenant `inbound_consecutive_failures` counter resets on the next successful reply push. To force a reset without waiting for a reply, contact Chert support.

Salesforce

HubSpot

Slack

Trust Boundary

OAuth Scopes

HubSpot Signature v3

Token Storage

Data Handling

Sub-processors

Incident Response

See Also

​Trust Boundary

​OAuth Scopes

​HubSpot Signature v3

​OAuth State Cookie

​Token Storage

​Data Handling

​Sub-processors

​Incident Response

​See Also

Trust Boundary

OAuth Scopes

HubSpot Signature v3

OAuth State Cookie

Token Storage

Data Handling

Sub-processors

Incident Response

See Also